From 0cdcb9abbb395073d18bc317cbda171726376f86 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Thu, 8 Mar 2012 22:38:52 +0000 Subject: [PATCH] Document conventions used in RST source git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25758 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/README | 46 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/doc/rst_source/README b/doc/rst_source/README index 1aacbbd2d..3260809a6 100644 --- a/doc/rst_source/README +++ b/doc/rst_source/README @@ -21,3 +21,49 @@ sphinx-build -b man source_dir destination_dir 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. -- 2.26.2