4.1 構文法

Python ドキュメントの作者は、LaTeX の構文法についていくつか知っておかねばならないことがあります。

コメント は、``パーセント'' 文字 ("%") から始まり、行末まで、または次の行の先頭にある空白文字まで 続きます。これは著者の知っているどのプログラミング言語とも少し違っています。そこで、順序立てて例を挙げます:

This is text.% comment
    This is more text.  % another comment
Still more text.

最初の行のコメントの以降で、コメントでないとみなされる最初の文字は、二行目の"T" になります; 二行目の先頭にある空白文字は、最初の行のコメントの一部として消費してしまいます。すなわち、最初と二つ目の文との間には全くスペースがなく、最初の行のピリオドと二行目の文字"T" はタイプセット時に直接くっついていると解釈されるのです。

二つ目のコメントの直後にくる非コメント文字は "S" ですが、二つ目のコメントの直前に空白を入れているため、意図通りに二つの単語が分割されることにも注意してください。

グループ は一連のテキストやコマンドに対する囲いで、フォーマット処理のコンテキストを囲い、コマンドが処理コンテキストに及ぼす変更の範囲をグループ内に制限します。グループは入れ子構造にして階層化できます。フォーマット処理のコンテキストは、フォントや、追加のマクロ定義 (またはグループ外部で定義されているマクロに対するオーバライド) を含みます。構文法的には、グループは波括弧で囲います:

グループを表すには、ブラケット [...] を使う代用構文もあります。この代用構文はオプションのパラメタをとるようなマクロや環境のコンストラクタで使います; ブラケットには通常、構文上の意味はありません。原始的要素 (atomic bit) が一つだけしか入っていない縮重グループ (degenerate group) の場合は、あいまいさを防ぐために必要でないかぎり明示的なグループにする必要はありません。とはいえ、 Python は明示的であることをよしとするので、ドキュメントのマークアップではグループを明示しましょう。

マクロや環境におけるパラメタをマークする場合を除き、Python ドキュメントではグループ自体は控えめに使います。

マクロ は通常は単純な構成要素で、マクロ名で識別され、いくつかのパラメタを取ることがあります。通常の LaTeX の使用法では、パラメタのうちの一つがオプションになっていることがあります。マークアップはバックスラッシュ文字 ("\") から始め、マクロ名はアルファベット文字 (数字、ハイフン、アンダースコア以外) で与えます。必須パラメタはグループとしてマークし、オプションのパラメタはグループの代用構文でマークせねばなりません。

例えば、単一のパラメタをとるマクロは以下のようになります:

マクロ名の後ろには空白や改行を入れてもかまいません; この場合、マクロ名とパラメタ間の空白は取り去られてしまいます。しかし、Python ドキュメントではこうした使い方を実践しません。空白はマクロにパラメタがない場合にも取り去られますが、この場合には空のグループ ({}) や、空白の明示的表現 ("\ ") をマクロ名の直後に続けると、マクロ展開が後続の文字に及ぶのを避ける手助けになります。パラメタを取らないが、後ろに空白を続けたくないマクロの場合には、ドキュメントソース中で名前の後ろに名前に使わない文字 (区切り文字など) が入っていれば、特別扱いする必要はありません。

例題中の各行は、パラメタをとらないマクロが入った文章を書くための適切な方法を示しています。

This \UNIX{} is followed by a space.
This \UNIX\ is also followed by a space.
\UNIX, followed by a comma, needs no additional markup.

環境はマクロよりも大きな構文要素です。環境は、マクロの引数に入れるには内容がやや大きすぎて便利さを欠く場合に使えます。主に、本文の大きな断片の前後でフォーマットパラメタを変更する必要があり、かつ本文を十分柔軟に書きたい場合に使います。サンプルコードは環境を使って表現します。また、関数、メソッド、クラスの定義も環境を使ってマークします。

環境の中に入る文章は自由な形式で、かつ複数の段落になる場合があるので、実際には二つのマクロからなるペア: \begin および \end を使ってマークします。これらのマクロはいずれも環境の名前をパラメタにとります。以下の例は、ドキュメントの概要をマークするために使う環境です:

\begin{abstract}
  This is the text of the abstract.  It concisely explains what
  information is found in the document.

  It can consist of multiple paragraphs.
\end{abstract}

環境は、環境自体の必須パラメタやオプションパラメタを持つこともあります。これらのパラメタは \begin マクロのパラメタの後ろに続けます。以下に単一の必須パラメタをとる環境の例を示します:

\begin{datadesc}{controlnames}
  A 33-element string array that contains the \ASCII{} mnemonics for
  the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
  (US), in order, plus the mnemonic \samp{SP} for the space character.
\end{datadesc}

ASCII に含まれない文字、特殊文字とされている文字、TeX や LaTeXで アクティブ (active) な文字を入力するための、あまり使われないマークアップがあります。これらのマークアップはよく他の文字に隣接して使われるので、適切な文字を生成するためには、マークアップの後ろにスペースや空のグループを置く必要があるかもしれません。あるいは、マークアップをグループ内に囲ってもかまいません。Python ドキュメントで使われるようなマークアップを以下にいくつか示します:

キャラクタ文字	マークアップ
^	`\textasciicircum`
~	`\textasciitilde`
>	`\textgreater`
<	`\textless`
ç	`\c c`
ö	`\"o`
ø	`\o`