The hope is to eventually turn the following into a sort of style guide for the TeX documentation. Andrew Kuchling amk@magnet.com Useful typographical things =========================== \ABC The ABC language \UNIX The UNIX operating system \ASCII The ASCII format \Cpp The C++ language \C The C language \EOF The end-of-file condition \sectcode{} Include the text as code; for use only in section headers Macros to highlight small bits of text ====================================== \key, \kbd Indicate a key to be struck (each used only once; do we need them both?) \samp An example of something; \samp{print} or \samp{pass} \var A variable value, like a placeholder for a parameter's value \file A file name \dfn A term being defined for the first time \emph, \strong Emphasizing text that's important (do we need them both?) \varvars{} Define something as being a variable; this escapes chars where \var does not \iftexi, \iflatex Only execute the following code if Texinfo or LaTeX is being used. Indexing ======== Indexing: \index{entry text} is the standard LaTeX indexing macro. ! separates the entry text into sections. Ex.: \index{encoding!base-64}. \indexii{A}{B} creates two entries: A, B and B, A Ex.: \indexii{numeric}{value} \indexiii{A}{B}{C} 3 entries: A, B C -- B, C A -- C, A B Ex.: \indexiii{checksum}{cryptographically}{strong} Indexing special things: statements stindex Ex.: \stindex{pass} operators opindex Ex.: \opindex{**} exceptions exindex Ex.: \exindex{ValueError} objects obindex Ex.: \obindex{code} built-in functions bifuncindex modules modindex built-in modules bimodindex standard modules stmodindex Environments ============ Functions: \begin{funcdesc}{name}{arg1\, arg2\optional{\, optarg1}} Exceptions: \begin{excdesc}{name} Module-level variables (usually constants): \begin{datadesc}{name} \bcode, \ecode Sizable blocks of code should be inside a verbatim environment, and *must* be bracketed by the \bcode and \ecode tags. Ex.: \bcode\begin{verbatim} class foo: pass \end{verbatim}\ecode Tables ====== \tableii{pattern}{column 1 style}{column 1 name}{column 2 name} \tableiii{pattern}{column 1 style}{column 1 name}{column 2 name}{column 3 name} Organization ============ Within a single chapter, modules should be listed in alphabetical order. In each module, all module-level things like functions and variables should also be in alphabetical order. XXX more stylistic comments required! ===================================== Macros used only once: \indexiv Unused LaTeX macros: \itembreak, \itemjoin, \funcitem, \dataitem, \excitem, \kwindex _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________