TCC Documentation Guidelines

An important theoretical underpinning of DocBook is to use structural markup and not descriptive markup. For example, there are several reasons to italicize English text. DocBook has a tag for each reason: emphasis for emphasized text; citetitle for titles of books, articles, or movies; and foreignphrase for phrases in a foreign language.

However, the Wiki italicization markup ''...'' doesn't define why the text is italicized. If exported to DocBook, all such text is wrapped in an emphasis element, even in cases where that is not the reason for italics.

If you have a bulleted or numbered list with items that run for more than one line, and any of the lines contain markup such as ''...'' for italics, the lines are not wrapped properly. Here is an example that fails:

-----
 1.  If you use ''italic'' or '''bold''' markup in the first
 line, you can continue the paragraph with explicit line breaks,
so long as no continuation line contains those kinds of markup.

 1.  However, if you use any continuation lines that contain
 any ''italic'' or '''bold''' markup, there will be a line break
 in the output at the same location as the line breaks in the input.
-----

As rendered by MoinMoin, step 2 has a line break after the word “contain”, so the first line is much too short.

The workaround is to make each bullet or step one huge long line. The Wiki apparently doesn't expect you ever to use the Enter key to break up long lines within a bullet or step.

In a DocBook procedure, one step can refer to a different step using a symbolic name. Internal step number references will be recomputed automatically.

For example, if step 7 says to go back to step 3, and then later someone adds a new step before step 3, this reference is now in step 8 and refers to step 4. MoinMoin won't handle this case automatically.

If you use numbers like 1., 2., 3. to number a list, everything works fine. However, if you use step numbers a., b., c., …, the indentation is incorrect: all steps after the first are indented an extra level. Try this test case:

   a. This is the first step.

   b. This is the second step.

   c. This is the third step

The workaround is always to let MoinMoin do the numbering for you. If you number the steps a., a., a., …, it works okay.

Simple tables are easy to build in MoinMoin, but some operations are tedious. For example, if you have a 200-line table and you want each entry in a given column to be right-aligned, you must use the special “<)>” marker just after the opening “||” on each line. DocBook tables allow you to describe the alignment of a column once initially, and that's all you need.

Inside a verbatim section enclosed in “{{{...}}}”, you can't get font changes. This makes it hard to show prototypes of program or file constructs, in which some of the parts are to be replaced. DocBook makes this easy: use replaceable elements inside a programlisting, and those elements will be shown in italic monospaced type.

There is a minor bug in the mechanism for WantedPages. This procedure reproduces the bug.

The workaround is to make some trivial edit on page A, such as adding a space at the end of a line somewhere. After saving the page, WantedPages will no longer show the spurious dead link report.