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