Documentation/DocConventions

   1 Manual pages structure:
   2
   3 - add references to all external commands mentioned anywhere in the text to the
   4   'SEE ALSO' section
   5   - also add related, not explicitly mentioned
   6 - the heading levels are validated
   7   - mandatory, manual page ===
   8   - mandatory, sections ---
   9   - optional, sub-sections ~~~
  10 - command-specific examples are mostly free of restrictions but should be
  11   readable in all output formats (manual page, html)
  12
  13 - subcommands are in alphabetical order
  14
  15 - long command output or shell examples: verbatim output
  16   - a new paragraph, 2 spaces at the beginning of the line
  17
  18
  19 Quotation in subcommands:
  20
  21 - exact syntax: monotype `usage=0`
  22 - reference to arguments etc: 'italics'
  23 - command reference: bold *btrfs fi show*
  24 - section references: italics 'EXAMPLES'
  25
  26 - argument name in option desciption: caps in angle brackets <NAME>
  27   - reference in help text: caps NAME
  28     also possible: caps italics 'NAME'
  29
  30 - command short description:
  31   - command name: bold *command*
  32   - optional unspecified: brackets [options]
  33   - mandatory argument: angle brackets <path>
  34   - optional parameter with argument: [-p <path>]
  35
  36
  37 Refrences:
  38 - full asciidoc syntax: http://asciidoc.org/userguide.html
  39 - cheatsheet: http://powerman.name/doc/asciidoc