summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Sterba <dsterba@suse.com>2017-05-18 18:49:00 +0200
committerDavid Sterba <dsterba@suse.com>2017-07-03 13:35:10 +0200
commitcc5c10b675dd54156536e01653ce6081e9f57576 (patch)
tree0f5c03ed20869752965d96856c4a0acde28a54a6 /Documentation
parent88221fc081a7a0979a012f243b66cf097382cc8f (diff)
btrfs-progs: docs: document conventions
Signed-off-by: David Sterba <dsterba@suse.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingConventions19
-rw-r--r--Documentation/DocConventions39
2 files changed, 58 insertions, 0 deletions
diff --git a/Documentation/CodingConventions b/Documentation/CodingConventions
new file mode 100644
index 00000000..cee90b30
--- /dev/null
+++ b/Documentation/CodingConventions
@@ -0,0 +1,19 @@
+C style
+-------
+
+The kernel CodingStyle where applicable
+
+https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+Error messages
+--------------
+
+* formatting:
+ * use `error("string ...")`
+ * no trailing newline
+ * small letter starts the first word
+ * no string splitting
+ * move string to new line if it's too long, un-indent to the left if it
+ exceeds 80 chars
+* contents:
+ * be descriptive
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 <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>]
+
+
+Refrences:
+- full asciidoc syntax: http://asciidoc.org/userguide.html
+- cheatsheet: http://powerman.name/doc/asciidoc