Plain-Text House Style (Setext-style) v6

QR code (opens latest published SOP)

Steps

1. Purpose
   Define an 82-column, ASCII-only, no-rendering House Style that is easy to read in any monospaced font. This document is self-demonstrating and may be used as a template.
2. Essentials
   • Width: wrap hard at 82 columns. Words must not be broken across lines.
   • Paragraphs: separate with exactly one blank line.
   • Headings: always insert one blank line before a heading; insert no blank line after the heading underline.
   • Headings use underline rules: '=' for H1 (this title), '-' for H2.
   • Deeper levels use numbered headings like '3. Title' and '3.1 Part'.
   • ASCII only: every character must be 1 byte (7-bit printable ASCII recommended).
   • Emphasis: use asterisks. *emphasis*, **more emphasis*, *EVEN MORE EMPHASIS*, **AS BOLD AS IT GETS**.
   • [Defined Term]: on first definition use square brackets and Capitalized Words. Thereafter, drop brackets and keep capitalization.
3. Headings
   Underline headings using '=' for H1 and '-' for H2. The underline length must exactly match the title text length. For H3 and deeper, prefer numbered headings. There should be NO blank lines between the heading and the start of the paragraph. There MUST be a blank line between the end of a paragraph and any heading.
4. Examples
   1. Design Details
   2. Data Model
   3. Entities
5. Lists
   Bulleted and numbered lists align wrapped lines under the text (two-space hanging indent for bullet items; three-space for numbered items).

   • Bulleted item that wraps onto the next line and keeps a tidy two-space hanging indent under the bullet.
   • Second item.

   1. Numbered item.
   2. Second item with a brief continuation to show alignment across lines.

   Lettered subitems may be used when helpful:

   1. Lettered subitem a.
   2. Lettered subitem b.
6. Defined Terms
   Use square brackets on first use to introduce formal terms that will recur. Capitalize the first letter of each word inside the brackets. Thereafter, refer to the term in first letter capitalized form without brackets.

   Example (first use of three terms): Acme Pty Ltd the [Company] and Bruce James Smith the [Employee] have agreed to the contents of this document, the [Agreement]. Later references (same document): the Company, the Employee, and the Agreement.

7. Definition Lists
   Keep each term on its own line with a simple ASCII dash separator.

   Company

   Acme Pty Ltd; defined above (first use in brackets).

   Employee

   Bruce James Smith; defined above (first use in brackets).

   [Party]

   the Company or the Employee are eacha Party to this Agreement, together the [Parties] to this agreement.

   Agreement

   The document agreed by the Company and the Employee.

   [Signature Page]

   the last page of the document on which the Parties, or a representative thereof signs this agreement.

8. Code and Commands
   Indent code and shell examples four spaces. Do not fence.

   $ widgetctl --status
   if [ $? -eq 0 ]; then
       echo OK
   fi
   

9. Tables (ASCII)
   Keep tables simple and narrow. Use '+', '-', and '|'.

   +--------------+----------------+--------------+
   | Term         | First Use      | Later Use    |
   +--------------+----------------+--------------+
   | Agreement    | [Agreement]    | Agreement    |
   | Company      | [Company]      | Company      |
   | Employee     | [Employee]     | Employee     |
   | Defined Term | [Defined Term] | Defined Term |
   +--------------+----------------+--------------+
   

10. Callouts
    Use NOTE and WARN as inline callouts; keep them brief. *NOTE*: Short actionable notes fit on a single line. **WARN**: Consequences if ignored.
11. Quoting
    Prefix quoted lines with '>' and nest with multiple '>'.

    > A quoted line that mentions the Agreement on later reference.
    > >> A deeper quote mentioning the Company and the Employee.
    > *This quoted line also shows emphasis markers.*
    

12. File Header (Template)
    Start each document with a title block as follows:

    Title of Document
    =================
    Author: Your Name
    Date:   2025-08-13
    

13. Checklist
    1. Width <= 82 columns; words are not broken; paragraphs separated by one blank line.
    2. Headings underlined ('=' for H1, '-' for H2); blank line before each heading; no blank line after the underline.
    3. Deeper levels use numbered headings where needed.
    4. Defined Terms introduced once in brackets; capitalized thereafter.
    5. Lists have hanging indents; definitions align cleanly.
    6. Emphasis uses *...* and **...** as described.
    7. Code is indented 4 spaces; tables are ASCII and narrow.
    8. Callouts and quotes are used where helpful, not noisy.
    9. ASCII-only: every character in the document is exactly 1 byte.