12.3. Style Guide
Prev | Chapter 12. Writing Style | Next

## 12.3. Style Guide

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>`

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 `&nbsp;` 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

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.