[PYTHON DOC-SIG] Notes on myformat.sty

[Andrew Kuchling]

	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
_______________