Applies to 2024-10

10 Formatting XML #

This section provides information on formatting XML sources.

Line ends: Lines should end with a Unix line end character (also called line feed, LF, newline, or \n).
Line length: Lines should be at most 100 characters long, unless one of the following exceptions applies:
- Some computer output, computer input or URIs may run longer and cannot be broken.
- Some elements become much harder to read if broken. For example, that can be the case for long <menuchoice/> elements.
- Aim to minimize the size of diffs in version control, to make reading diffs more efficient and version control storage more efficient. For example, if a typo fix introduces a line with 82 characters, consider keeping the line at that length. Also, avoid reflowing entire paragraphs of text, as that will also lead to hard-to-read diffs.
Indentation: Indent using two space characters per indentation level. Make sure your editor does not replace spaces with tabs. Documents should not contain any tab characters.
Trailing whitespace: Avoid introducing trailing whitespace characters such as spaces, protected spaces or tabs. Many editors have an option to view such characters. git diff will show newly introduced trailing whitespace characters in red.
Formatting of block elements: Block elements are all DocBook elements that create a rectangular visual block in the layout, such as <para/>, <table/> or <figure/>. Format block elements with new lines before and after each tag and make sure they follow the indentation of the document:
```
<block>
 Content of block, indented by a space.
</block>
```
For information about the usage of <screen/>, see Section 7.4.6, “Screens”.
Formatting of inline elements: Block elements are all DocBook elements that can be reflowed freely within a block element, such as <emphasis/>, <keycap/>, or <guimenu/>. Format inline elements along with other inline content without adding newlines or extra indentation:
```
<block>
 Content of block <inline>content of inline</inline>.
<block>
```
Formatting of title elements: The title elements <title/> and <term/> are block elements. However, they provoke a style sheet quirk and should be treated differently. This avoids superfluous whitespace when used in the context of a cross-reference. Format title elements with new lines before the opening tag and after the closing tag and make sure they follow the indentation of the document:
```
<title>Content of Title</block>
```
Formatting of computer output/computer input blocks: The Computer Output/Computer Input Block Element <screen/> should be treated like a block element but multi-line <screen/> elements should not be indented to aid source reading flow and avoid the trap of adding extraneous leading space to their content. (Single-line <screen/> can be indented).
XML comments. XML comments should follow the indentation of the document. Where feasible, put XML comments on new lines to make reading diffs and later removal of the comment easier:
```
<block>
 Block content.
 
</block>
```
XML comments must not contain the characters --. To preserve such character combinations within comments, replace them with -/-.
For information about the usage of XML comments, see Section 9.2, “XML comments”.
Reflowing entire files: Before reflowing entire files to a different XML formatting style, weigh the cost of keeping the document in its current state against the cost of reflowing. Reflowing often makes it easier to work with the document. However, if the document has a rich editing history already, reflowing makes it harder to properly use tools like git blame.

To easily convert documents to this style after importing them, use the commands daps xmlformat (for an entire document) and daps-xmlformat (for a single file). Note that while these tools are very good otherwise, they do not reflow XML comments properly.