12.3. Style Guide

12.3. Style Guide
Prev	Chapter 12. Writing Style	Next

To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions.

12.3.1. Letter Case

Tags are entered in lower case, para, not PARA.

Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>.

12.3.2. Acronyms

Acronyms should be defined the first time they appear in a document, as in: “Network Time Protocol (NTP)”. After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document.

All acronyms should be enclosed in acronym tags.

12.3.3. Indentation

The first line in each file starts with no indentation, regardless of the indentation level of the file which might contain the current file.

Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line.

For example, the source for this section looks like this:

<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <para>The first line in each file starts with no indentation,
	<emphasis>regardless</emphasis> of the indentation level of
	the file which might contain the current file.</para>

      ...
    </sect2>
  </sect1>
</chapter>

Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags:

<para>See the <link
    linkend="gmirror-troubleshooting">Troubleshooting</link>
  section if there are problems booting.  Powering down and
  disconnecting the original <filename>ada0</filename> disk
  will allow it to be kept as an offline backup.</para>

<para>It is also possible to journal the boot disk of a &os;
  system.  Refer to the article <link
    xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
    Journaling on a Desktop PC</link> for detailed
  instructions.</para>

When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting:

<para>With file flags, even
  <systemitem class="username">root</systemitem> can be
  prevented from removing or altering files.</para>

Configurations to help various text editors conform to these guidelines can be found in Chapter 13, Editor Configuration.

12.3.4. Tag Style

12.3.4.1. Tag Spacing

Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not:

<article lang='en'>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

12.3.4.2. Separating Tags

Tags like itemizedlist which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves.

Tags like para and term do not need other tags to contain normal character data, and their contents begin immediately after the tag, on the same line.

The same applies to when these two types of tags close.

This leads to an obvious problem when mixing these tags.

When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented.

When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line.

12.3.5. Whitespace Changes

Do not commit changes to content at the same time as changes to formatting.

When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace.

For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators.

12.3.6. Non-Breaking Space

Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one:

Data capacity ranges from 40 MB to 15
GB.  Hardware compression …

The general entity   prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places:

between numbers and units:
```
57600&nbsp;bps
```
between program names and version numbers:
```
&os;&nbsp;9.2
```
between multiword names (use with caution when applying this to more than 3-4 word names like “The FreeBSD Brazilian Portuguese Documentation Project”):
```
Sun&nbsp;Microsystems
```

Prev	Up	Next
12.2. Guidelines	Home	12.4. Word List