Reference Documentation Style Guide

The Reference Documentation for Seam and Web Beans is composed in DocBook (V4.5). DocBook is an XML grammar suited for writing books and papers about computer-oriented subjects. Therefore, it is a good fit for software framework documentation. For more information about DocBook, see the DocBook 4.5 Specification.

XML Formatting

Since DocBook is an XML syntax, the problem of formatting presents itself almost immediately. Every XML editor seems to have its own idea of how to format an XML document. If you allow your editor to format the document however it wants, and different contributors use different editors, then the document is going to be continuously reflowed. As a result, detecting which paragraphs changed from revision to revision becomes very difficult.

So we need rules.

Here are the rules. Disable auto-formatting of XML! Now, when you edit the document, whichever paragraphs you touch will need to be reflowed. For now, the recommended tool for this job is either VIM or JTidy.

Here are the rules.

• Spaces not tabs!
• Indent == 3 spaces
• Text Width == 120 characters

Make sure that endlines to not appear before symbols such as a comma, a period and brackets (unless intentional).

If you want to accomplish this in VIM, here's how.

:set tw=120
:set expandtab
:set ts=3
:set sw=3

At the bottom of each file are VIM modelines which set these options. So if modelines are enabled, you don't have to do anything.

Now, go to the paragraph you want to format. Enter a newline before the closing XML tag (e.g., </para>). Type these characters in normal mode:

gq]

Remove the endline before the closing tag.