summaryrefslogtreecommitdiff
path: root/Documentation/DocConventions
blob: 969209cfdc8d3995b838f471359f22f427024bdb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
Manual pages structure:

- add references to all external commands mentioned anywhere in the text to the
  'SEE ALSO' section
  - also add related, not explicitly mentioned
- the heading levels are validated
  - mandatory, manual page ===
  - mandatory, sections ---
  - optional, sub-sections ~~~
- command-specific examples are mostly free of restrictions but should be
  readable in all output formats (manual page, html)

- subcommands are in alphabetical order

- long command output or shell examples: verbatim output
  - a new paragraph, 2 spaces at the beginning of the line


Quotation in subcommands:

- exact syntax: monotype `usage=0`
- reference to arguments etc: 'italics'
- command reference: bold *btrfs fi show*
- section references: italics 'EXAMPLES'

- argument name in option description: caps in angle brackets <NAME>
  - reference in help text: caps NAME
    also possible: caps italics 'NAME'

- command short description:
  - command name: bold *command*
  - optional unspecified: brackets [options]
  - mandatory argument: angle brackets <path>
  - optional parameter with argument: [-p <path>]


References:
- full asciidoc syntax: http://asciidoc.org/userguide.html
- cheatsheet: http://powerman.name/doc/asciidoc