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