##
4.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 の 使用法では、パラメタのうちの一つがオプションになっていることが あります。マークアップはバックスラッシュ文字 ("`\`") から 始め、マクロ名はアルファベット文字 (数字、ハイフン、アンダースコア以外) で与えます。必須パラメタはグループとしてマークし、 オプションのパラメタはグループの代用構文でマークせねばなりません。

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

    \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`