Markup language
The markup language for this CMS doesn’t have a name, so it’s referred to as “markup” in this documentation. It’s inspired by lightweight markup languages such as Markdown, but it’s specifically written for the Dauucumentation.
General rules of the road
Edit in plain text.
Don’t indent it.
HTML treats consecutive spaces as a single space. So just use single spaces.
Separate paragraphs with a blank line.
Don’t include images. They aren’t implemented.
Peculiar characters
The CMS will convert your "straight quotes" to “curly quotes.”
Same idea with apostrophes; i.e., can't becomes can’t.
Use a tilde (~) to obtain a Unicode minus sign: ~54321 becomes −54321.
Use two hyphens to obtain an en dash: --aside-- becomes –aside–.
Use three hyphens to obtain an em dash: ---aside--- becomes —aside—.
A single-hyphen just stays a single-hyphen.
Font styles
A pair of one *asterisk* will italicize.
A pair of two **asterisks** will boldface.
A pair of three ***asterisks*** will bold italic.
A pair of four ****asterisks**** will superscript.
An unbalanced **asterisk series will produce an error message and stop the CMS.
I recognize that four asterisks is horrible notation for superscript; however, I don’t need it frequently, and this scheme does not require introducing any new special characters. I asked the CSS for superscript to not adjust line spacing.
Headings
A two-line paragraph, where the second line is straight hyphens, will produce a top-level <h1> heading. The markup looks like this:
Text at the top ---------------
You get an <h2> heading by having every 2nd character be a hyphen. Like this:
Second-level heading - - - - - - - - - -
Third-level heading working example
You get an <h3> heading by having every 3rd character be a hyphen. Like this:
Third-level heading working example - - - - - - - - - - - -
There may or may not be support for further heading levels. Note that heading levels, which affect only the right (article) column, have nothing to do with menu levels, which only appear in the left (menu) column.
Links
Square brackets will produce hyperlinks. Not much customization is supported, but link and title (mouseover) text can be set off with vertical bars as follows:
[https://example.com] yields https://example.com
[https://example.com|this site] yields this site
[https://example.com|question|Have you read RFC 6761?] yields question
Reserved symbols
To achieve the above markup, the following symbols were given special meaning:
- hyphen, en dash, em dash ~ minus sign " left and right double quotation mark ' right single quotation mark * italic, bold, bold italic, superscript ` monospace [ hyperlink start ] hyperlink end
So how do we get these characters to appear in text without their special meanings? What we don’t do is escape them in the manner of many common languages (e.g., \" in C). The reason for this is that escaping makes the unprocessed markup hard to read. Instead, we choose an unused character to temporarily assume the special meaning that’s in the way. Consider the following short paragraph:
To get italicized text, use asterisks like this: *This is italicized.*
The actual markup to produce the above is:
To get italicized text, use asterisks like this: `*This is italicized.*` *$
There are two lines of markup here. On the first line, we see ` used for its normal function of monospacing. But the * symbol isn’t italicizing, but is simply being printed verbatim. The second line of markup is controlling that: it contains a digraph consisting of one reserved symbol, *, and one unreserved symbol that isn’t used in the paragraph, $. This digraph tells the CMS to reassign any special meaning for * to $ instead, making * free for use as an ordinary character.
These digraph substitutions work for ordinary paragraphs as well as headings. They apply only to the paragraph or heading they are attached to. For the digraphs to be picked up, they appear by themselves on the last line of the heading or paragraph. Multiple substitutions are permitted and will need to be separated by spaces. A digraph pair is only recognized if one symbol ordinarily has a special meaning, and the other symbol does not.
Choosing a replacement symbol
The replacement symbol can't be -, ~, ", ', *, `, [, or ] due to their special meanings. It can't be whitespace either. And most subtly, it can't be <, &, or >, because the quoting XHTML requires for these characters confuses the CMS, and straightening that out is not a priority for now. Unicode's middle dot ยท (0xB7) also has special meaning. It's only used for tables, but it can't replace another character with special meaning anywhere for the time being. But you can use any digits, letters, much punctuation, and non-ASCII UTF-8 symbols. If this sounds too complex, just try to use $ or @ if you can.
More complex digraph substitution examples
Here are how I marked up a couple of paragraphs in this section:
There are two lines of markup here. On the first line, we see !`! used for its normal function of monospacing. But the !*! symbol isn't italicizing, but is simply being printed verbatim. The second line of markup is controlling that: it contains a _digraph_ consisting of one reserved symbol, !*!, and one unreserved symbol that isn't used in the paragraph, !$!. This digraph tells the CMS to reassign any special meaning for !*! to !$! instead, making !*! free for use as an ordinary character. `! *_
The replacement symbol can't be :-:, :~:, :":, :':, :*:, :`:, :[:, or :]: due to their special meanings. It can't be whitespace either. And most subtly, it can't be :<:, :&:, or :>:, because the quoting XHTML requires for these characters confuses the CMS, and straightening that out is not a priority for now. But you can use any digits, letters, much punctuation, and non-ASCII UTF-8 symbols. -\ ~\ "\ '\ *\ `: [\ ]\
Preformatted text
Obviously some mechanism is needed (and present) for presenting text that (i) is not flowed into paragraphs, (ii) is monospace throughout with tabs lining up, and (iii) leaves all characters as they originally appear. This is done by indenting the markup three or more spaces, and replacing the first space with the letter p for preformatted. For example, to produce this table:
x sqrt x ---------- 0 0.000 1 1.000 2 1.414 3 1.732 4 2.000 5 2.236
The markup that produces the table is:
p x sqrt x
----------
0 0.000
1 1.000
2 1.414
3 1.732
4 2.000
5 2.236
Here is an example with blank lines:
avocado bignay cocoplum agung bak carillon anthology biography collection
Here is the markup for that—only the first line should be tagged with p:
p avocado
bignay
cocoplum
agung
bak
carillon
anthology
biography
collection
What stops preformatted text from being interpreted as ordinary text?
Two “rules of the road” appeared at the top of this page: don’t indent, and use single spaces. Preformatted text is indented, and the p tag is followed by at least two spaces.
Alternative spacing for preformatted text
Tagging preformatted text with a capital P instead of p will reduce the vertical separation between the block and the surrounding paragraphs. It will also indent the preformatted text a little. It’s intended for one-liners within ongoing ideas, such as:
Without secure hardware, there is no secure software.
The markup for the above looks like:
P Without secure hardware, there is no secure software.
Assembler source code
Dauug|36 assembler code should be tagged with an a for assembler instead of p. This will turn on syntax highlighting (once available). For example, to produce:
unsigned count
count = 0
loop:
cmp count - 10
jump <= done
; do something with count here
jump loop
done:
; move on
Use markup like:
a unsigned count
count = 0
loop:
cmp count - 10
jump <= done
; do something with count here
jump loop
done:
; move on
Alternative spacing for assembler source code
Tagging assembly language with a capital A instead of a will reduce the vertical separation between the block and the surrounding paragraphs. It will also indent the code a little. It’s intended for one-liners within ongoing ideas, such as:
m = b mhl5 a
The markup for the above looks like:
A m = b mhl5 a
Bullets and numbering
Limited support for unordered and ordered lists is available using markup similar to preformatted text. List support is intended for one-liners, not for paragraphs or anything fancy. For numbers:
# one
two
three
produces:
- one
- two
- three
For bullets:
* alpha
beta
gamma
produces:
- alpha
- beta
- gamma
Nested lists are not supported. Formatting in lists is supported, and digraph substitution is possible on an entire-list basis.