Notice to readers: I would love any comments on the approach described here, particularly with respect to squaretags.
DomesuWiki is a wiki codebase by ChuckAdams (henceforth referred to in the first person), based on UseModWiki. I started it as a sort of cleanup effort and got carried away. I later mothballed it for a time, but have since pulled it out again. I have other aims for a wiki codebase, but they're likely to use the same ideas for syntax as Domesu.
Domesu's syntax is intended to be accessible to UseMod users, but not 100% compatible. By selectively enabling and disabling parts of the syntax, one can end up with a wiki with far different markup than UseMod. Currently the broad categories of syntax that are recognized are:
- WikiWords -- Supported, though Freelinks are preferred, and in fact the only way of constructing links with behaviors other than the default.
- Glyphs -- Refers to leading : (indent), :; (dd/dl) * (bullet), # (numbered list), spaces (for monospace), dashes (for lines) and other visual markup. Some glyphs are in their own categories
- Ticks -- This refers to the two, three, and five single quote markup of c2 and usemod.
- Email -- Conventions like _underline_, *bold*, and /italic/
- SomeHTML -- Limited HTML tags such as <b> or <i>
- AllHTML -- Any and all HTML tags. Not at all recommended for public wikis, XSS attacks are quite possible
- Misc -- Oddities like <nowiki> and __TOC__.
- SquareTags -- Support for web board style square tags, explained under separate cover. The actual canonical markup of Domesu. Disabling it only disables their parsing from the interface, as they're used internally.
Squaretags
Many web boards support some HTML tags entered using square brackets, e.g. [b]this is bold[/b]. Using a different bracket makes the translation simpler to implement than if it were raw HTML, and those using U.S. keyboards often find the square brackets slightly easier to type than angled ones. Additionally such tags can be overloaded or invented without confusing them with HTML tags, so you'll often see emoticons (smilies) implemented with such tags, e.g. [:frown] or [:laugh]. Domesu takes square tags and runs with them, to where every piece of wiki markup can be implemented with squaretags. This canonical representation makes rendering policy simple: whatever is inside unescaped square brackets belongs to the Wiki, the rest is literal text.
Square brackets dispatch their particular operation (usually parsing) based on the first character they encounter:
- [[ - Begin parsing a FreeLink. Example: [[sample free link]]
- [$ - Begin parsing a substitution. Example: Hello, [$username].
- [# - Begin parsing an immediate directive. Example: [#include disclaimer]
- [@ - Begin parsing a command. Example: [@style bigred = color red, font-size bigger]
- [tagname - Introduce an element, which may be a paragraph or block element. Usually just an HTML tag. Example: [strong]This is strong text[/strong].
- [tagname.class - Introduce an element using a class selector, which may be given a style previously. Example: [span.bigred]Text in red has a "good" or "go" connotation in chinese idiom[/span]
- [tagname.class+class - Syntactic sugar for inserting <span> tags with the CSS class immediately following the tag. Example: [h1.pagehead+username]Chuck Adams[/h1]. Not the most proper way to design, but convenient.
FreeLink syntax
The base syntax is similar to usemod
- [[Free Link]]
- [[Free Link|Link Description]]
However, there is now a third section allowed, namely "link options". This allows one to specify options to links, such as:
- [[ChuckAdams|new, tooltip="The one and only, thank god"|Chuck's Home Page]]
Options can be enabled and disabled independently. The annoyance factor of these can of course be minimized by blatantly editing them out :)