From cc5c10b675dd54156536e01653ce6081e9f57576 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 18 May 2017 18:49:00 +0200 Subject: btrfs-progs: docs: document conventions Signed-off-by: David Sterba --- Documentation/DocConventions | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/DocConventions (limited to 'Documentation/DocConventions') diff --git a/Documentation/DocConventions b/Documentation/DocConventions new file mode 100644 index 00000000..e84ed7a7 --- /dev/null +++ b/Documentation/DocConventions @@ -0,0 +1,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 desciption: caps in angle brackets + - 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 + - optional parameter with argument: [-p ] + + +Refrences: +- full asciidoc syntax: http://asciidoc.org/userguide.html +- cheatsheet: http://powerman.name/doc/asciidoc -- cgit v1.2.3