svn rev #25758: trunk/doc/rst_source/

[ghudson@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=25758
Commit By: ghudson
Log Message:
Document conventions used in RST source.


Changed Files:
U   trunk/doc/rst_source/README
Modified: trunk/doc/rst_source/README
===================================================================
--- trunk/doc/rst_source/README	2012-03-08 21:50:06 UTC (rev 25757)
+++ trunk/doc/rst_source/README	2012-03-08 22:38:52 UTC (rev 25758)
@@ -21,3 +21,49 @@
 
 The list of manual pages to be built should be constructed under man_pages section on conf.py
 
+
+CONVENTIONS
+===========
+
+We use the following conventions:
+
+* Use four-space indentation where indentation levels are arbitrary.
+  Do not use tabs anywhere.  Avoid trailing whitespace at the end of
+  lines or files.
+
+* Fill lines to 70 columns (the emacs default) where lines can be
+  wrapped.
+
+* For section headers, use === underlines for page titles, --- for
+  sections, ~~~ for subsections, and ### for sub-subsections.  Make
+  underlines exactly as long as titles.  Do not include trailing
+  punctuation in section headers.  Do not capitalize section headers
+  (except for the first word) except in source files intended to
+  generate man pages.
+
+* For bullet lists, use * for top-level bullets and - for sub-bullets.
+  Do not indent bullet or enumerated lists relative to the surrounding
+  text.
+
+* Use italics (*word*) for words representing variables or parameters.
+  Use boldface (**word**) for command options, subcommands of programs
+  like kadmin, and krb5.conf/kdc.conf parameter names.  Use literal
+  text (``text``) for examples and multi-component pathnames.  For
+  command names, single-component filenames, and krb5.conf/kdc.conf
+  section names, use references (like :ref:`kadmin(1)`) if introducing
+  them, or just use them unadorned otherwise.
+
+* In man pages for commands with subcommands, make a subsection for
+  each subcommand.  Start the subcommand with an indented synopsis,
+  then follow with non-indented text describing the subcommand and its
+  options.  See kadmin_local.rst for an example.
+
+* In man page synopses, put a newline in the RST source before each
+  option.  Put all parts of the synopsis at the same indentation
+  level.  Ideally we would want a hanging indent to the width of the
+  command or subcommand name, but RST doesn't support that.  Use
+  boldface for literal text in the synopsis, italics for variable
+  text, and unadorned text for syntax symbols (such as square brackets
+  to indicate optional parameters).  If immediately following one kind
+  of inline markup with another or putting inline markup next to
+  punctuation, you may need to use "\ " as a dummy separator.