62ee9a50bf
Rename to asciidoc as that's the format we use for manual page source. Signed-off-by: David Sterba <dsterba@suse.com>
53 lines
1.8 KiB
Plaintext
53 lines
1.8 KiB
Plaintext
Convention and style used for manual pages
|
|
------------------------------------------
|
|
|
|
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, or the comment block
|
|
|
|
Quotation in subcommands:
|
|
|
|
- exact syntax: monotype `usage=0`
|
|
- reference to arguments etc: 'italics'
|
|
- command reference: bold *btrfs filesystem show*
|
|
- subcommand names should be spelled in full, ie. 'filesystem' instead of 'fi'
|
|
- 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>]
|
|
|
|
Other:
|
|
|
|
- NOTE: at the beginning of the line, is rendered as a separate paragraph and
|
|
should be used only for important information
|
|
|
|
- WARNING: at the beginning of the line, is rendered as a separate paragraph
|
|
and most likely more visible than NOTE, use for critical information that
|
|
may cause harm, irreversible state or performance problems
|
|
- should point reader to other part of documentation to seek more details
|
|
|
|
|
|
References:
|
|
- full asciidoc syntax: http://asciidoc.org/userguide.html
|
|
- cheatsheet: http://powerman.name/doc/asciidoc
|