Documenting Python

Previous: 6.11 Index-generating Markup Up: 6 Special Markup Constructs Next: 7 Graphical Interface Components

---

 
6.12 Grammar Production Displays

Special markup is available for displaying the productions of a formal grammar. The markup is simple and does not attempt to model all aspects of BNF (or any derived forms), but provides enough to allow context-free grammars to be displayed in a way that causes uses of a symbol to be rendered as hyperlinks to the definition of the symbol. There is one environment and a pair of macros:

\begin{productionlist} [language]
\end{productionlist}

This environment is used to enclose a group of productions. The two macros are only defined within this environment. If a document descibes more than one language, the optional parameter language should be used to distinguish productions between languages. The value of the parameter should be a short name that can be used as part of a filename; colons or other characters that can't be used in filename across platforms should be included.

\production {name}{definition}

A production rule in the grammar. The rule defines the symbol name to be definition. name should not contain any markup, and the use of hyphens in a document which supports more than one grammar is undefined. definition may contain \token macros and any additional content needed to describe the grammatical model of symbol. Only one \production may be used to define a symbol -- multiple definitions are not allowed.

\token {name}

The name of a symbol defined by a \production macro, used in the definition of a symbol. Where possible, this will be rendered as a hyperlink to the definition of the symbol name.

Note that the entire grammar does not need to be defined in a single \productionlist environment; any number of groupings may be used to describe the grammar. Every use of the \token must correspond to a \production.

The following is an example taken from the Python Reference Manual:

\begin{productionlist}
  \production{identifier}
             {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
  \production{letter}
             {\token{lowercase} | \token{uppercase}}
  \production{lowercase}
             {"a"..."z"}
  \production{uppercase}
             {"A"..."Z"}
  \production{digit}
             {"0"..."9"}
\end{productionlist}

---

Documenting Python

Previous: 6.11 Index-generating Markup Up: 6 Special Markup Constructs Next: 7 Graphical Interface Components

---

Release 2.2.2, documentation updated on October 14, 2002.