4 See doc/build_this.rst for details about how to build the
11 We use the following conventions:
13 * Use four-space indentation where indentation levels are arbitrary.
14 Do not use tabs anywhere. Avoid trailing whitespace at the end of
17 * Fill lines to 70 columns (the emacs default) where lines can be
20 * For section headers, use === underlines for page titles, --- for
21 sections, ~~~ for subsections, and ### for sub-subsections. Make
22 underlines exactly as long as titles. Do not include trailing
23 punctuation in section headers. Do not capitalize section headers
24 (except for the first word) except in source files intended to
27 * For bullet lists, use * for top-level bullets and - for sub-bullets.
28 Do not indent bullet or enumerated lists relative to the surrounding
31 * Use italics (*word*) for words representing variables or parameters.
32 Use boldface (**word**) for command options, subcommands of programs
33 like kadmin, and krb5.conf/kdc.conf parameter names. Use literal
34 text (``text``) for examples and multi-component pathnames. For
35 command names, single-component filenames, and krb5.conf/kdc.conf
36 section names, use references (like :ref:`kadmin(1)`) if introducing
37 them, or just use them unadorned otherwise.
39 * In man pages for commands with subcommands, make a subsection for
40 each subcommand. Start the subcommand with an indented synopsis,
41 then follow with non-indented text describing the subcommand and its
42 options. See kadmin_local.rst for an example.
44 * In man page synopses, put a newline in the RST source before each
45 option. Put all parts of the synopsis at the same indentation
46 level. Ideally we would want a hanging indent to the width of the
47 command or subcommand name, but RST doesn't support that. Use
48 boldface for literal text in the synopsis, italics for variable
49 text, and unadorned text for syntax symbols (such as square brackets
50 to indicate optional parameters). If immediately following one kind
51 of inline markup with another or putting inline markup next to
52 punctuation, you may need to use "\ " as a dummy separator.
54 * For directives that take a content block (e.g., note, error, and
55 warning), leave a blank line before the content block (after any
56 arguments or options that may be present).