##
1 構文法

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

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

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

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

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

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

    {text in a group}

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

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

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

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

    \name{parameter}

オプションのパラメタをとるマクロで、パラメタを指定するときには以下の ように入力します:

    \name[optional]

オプションと必須パラメタの両方が必要な場合には、以下のようになります:

    \name[optional]{required}

マクロ名の後ろには空白や改行を入れてもかまいません; この場合、マクロ名と パラメタ間の空白は取り去られてしまいます。しかし、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`