Formatting in Plain-Text Documents
==================================

The document title uses title case and is underlined with equal signs.
There is only one blank line above the document title.


PRIMARY HEADINGS

Level-1 headings use uppercase letters.  They are not underlined.


Secondary Headings
------------------

Level-2 headings use title case and are underlined with hyphens.


BULLETED LISTS

Bulleted lists typically are introduced by a complete sentence that
ends with a colon:

 *  This is a level-1 bullet item.

 *  A level-1 bullet item begins with a space, an asterisk, and two
    more spaces.

    Text within a bullet item is left-aligned with the first character
    in the bullet item that is neither a space nor the bullet.  Here's
    a level-2 bulleted list:

     -  This is a level-2 bullet item.

     -  A level-2 bullet item begins with a space, a hyphen, and two
        more spaces, in addition to the number of spaces taken up by
        the "parent" list.


NUMBERED LISTS

A numbered (or "ordered") list should comprise steps to be performed
in a particular order.  Format the list like this:

  1.  <Step one here>  If a list-item number comprises a single digit,
      the list item begins with two spaces, the number, a period, and
      two more spaces.  If the list-item number comprises two digits,
      the list item begins with *one* space, the number, a period, and
      two more spaces.  Subsequent lines in any list item are always
      left-aligned with the first character of the list item's
      main text.

      This is the second paragraph in the first step.

  2.  <Step two here>  Here's a bulleted list nested inside a
      numbered list:

        *   Bullet item

        *   Another bullet item

  3.  <Step three here>  Here's a level-2 numbered list:

        a)  <First sub-step>

        b)  <Second sub-step>

  4.  <Step four here>


SPACING

There is one blank line above a paragraph; there are two blank lines
above a heading (except at the top of the file, as noted at the top of
*this* file).

There are two spaces after a colon or a sentence-ending punctuation
mark, unless it is the end of the paragraph.

  NOTE:  White space at the end of a paragraph is not characteristic
  of professional communication.

Tab characters should not appear in a plain-text document unless it is
a tab-delimited data file.  Set your text editor to substitute four
spaces for a tab.


TEXT WRAPPING

In a text file, the maximum line width should be 70 characters for a
readme or similar document, 64 characters for an e-mail message, and
76 characters for source code or for command-line output.

  Note:  Try to avoid "orphans" (single words on the last line of a
  paragraph), even if it means wrapping a word that would actually fit
  on the second-to-last line.

To make a 70-character ruler:  Type four periods, a colon, four more
periods, and a vertical bar; then, copy this segment, and paste it
seven times.  It should look like this:

....:....|....:....|....:....|....:....|....:....|....:....|....:....|


TEXT FORMATTING


Emphasis
--------

Use asterisks to emphasize in-line words:

    This is *really* important.

Avoid the use of all-caps:

    THIS IS CONSIDERED "SHOUTING".


Cross-References
----------------

If you refer to the title of another section in the same document,
enclose the name in double quotation marks, and set the name in
title case (regardless of what level of heading it is).

For example, "Primary Headings" and "Secondary Headings" are
both sections within this document.


Indentation
-----------

Indent notes and cautions by two spaces.  Indent code samples and
block citations by four spaces.