6.5 インラインマークアップ
この節で説明するマクロは、単にドキュメントテキスト中の興味深い内容を
マークするために使われます。これらのマクロは、本文だけではなく、
表題に利用してもかまいません (とはいえ、ハイパーリンクを含むものは
除かねばなりません)。
- \bfcode
{text}
-
\code に似ていますが、ボールド書体にします。
- \cdata
{name}
-
C言語における変数の名前です。
- \cfunction
{name}
-
C言語における関数の名前です。name には関数名とその後ろの丸括弧
を含めねばなりません。
- \character
{char}
-
1 バイトの文字列値ではなく、単一の文字について議論する場合の文字です。
文字は \samp と同じようにタイプセットされます。
- \citetitle
[url]{title}
-
参照している出版物のタイトルです。url を指定すると、
タイトル部分は HTML 形式にフォーマットした際にハイパーリンクになります。
- \class
{name}
-
クラス名です; ドット名表記を使用できます。
- \code
{text}
-
短いコード断片や定数リテラル。引用符で囲わないので、スペースを
入れてはなりません。
- \constant
{name}
-
``定義済みの'' 定数名です。C 言語における #define や、
変更されないことになっている Python の変数の場合があります。
- \csimplemacro
{name}
-
``単純'' マクロの名前です。単純マクロは、引数を取らないため
関数で記述できないようなコードの展開に使われます。
この環境は単純な定数定義には用いません。
Python ドキュメント内でのこのマクロの用例としては、
PyObject_HEAD やPy_BEGIN_ALLOW_THREADS が
あります。
- \ctype
{name}
-
C の typedef や構造体の名前です。
型がtypedef を伴わずに定義されている構造体の場合は、
\ctype{struct struct_tag} を使って、struct
が必須であることを明示してください。
- \deprecated
{version}{what to do}
-
説明している内容がリリース version 以降で撤廃されていることを
宣言します。
what to do に指定したテキストでは、撤廃されたものの代わりに
利用すべきものを推奨せねばなりません。テキストは完全な文にせねば
なりません。文章全体に対して撤廃を注釈する場合、別個の段落にして
表示せねばなりません; この場合、撤廃される機能の説明の前か後ろの
どちらかに置きます。
- \dfn
{term}
-
テキストにおけるterm のインスタンスの定義をマークします。
(索引エントリを生成しません。)
- \e
-
バックスラッシュを生成します。\code 、\file や類似の
マクロ、および \alltt 環境の内容を記述する場合に便利で、そうした
マークアップ内だけ定義されています。
(\citetitle マクロの中身のような) 通常の文章でバックスラッシュを
生成する場合には、標準の \textbackslash マクロを使ってください。
- \email
{address}
-
電子メールアドレスです。出力形式が何であれ、ハイパーリンクは
行われない ので注意してください。アドレスのドメインネーム部分は
小文字でなければなりません。
- \emph
{text}
-
強調テキストです。イタリックフォントで表示されます。
- \envvar
{name}
-
環境変数です。索引エントリを生成します。
- \exception
{name}
-
例外の名前です。ドット名表記を使えます。
- \file
{file or dir}
-
ファイルやディレクトリの名前です。PDF と PostScript 形式の出力では
ファイル名を表現するのに単引用符で囲ってフォントを変更しますが、
HTML 出力では引用符囲いを行いません。
警告:
処理上の制約により、\file マクロはセクションタイトル内の
内容には使えません。
- \filenq
{file or dir}
-
\file に似ていますが、単引用符を使いません。テーブルと組み合わせる
際に、カラムにファイルやディレクトリ名だけが入るような場合に使えます。
警告:
処理上の制約により、\filenq マクロはセクションタイトル内の
内容には使えません。
- \function
{name}
-
Python 関数の名前です; ドット名表記を使えます。
- \infinity
-
数学的な無限大を表すシンボル: ∞です。このシンボルの
HTML 表現を適切に描画できないブラウザもありますが、サポートは
拡大しています。
- \kbd
{key sequence}
-
キーシーケンスをマークします。key sequence がどんな形式になるかは
プラットフォームやアプリケーション固有の取り決めに依存します。
適当な取り決めがない場合には、初心者や別のシステムを利用している
人たちが分かりやすいように、モディファイアキー名を書き下さねば
なりません。例えば、xemacs のキーシーケンスは
\kbd{C-x C-f} のようにマークできますが、特定のアプリケーション
やプラットフォームに対する参照を行わない場合には、
\kbd{Control-x Control-f} とマークせねばなりません。
- \keyword
{name}
-
プログラミング言語における予約語 (keyword) の名前です。
- \mailheader
{name}
-
RFC 822 形式のメイルヘッダ名です。このマークアップは、そのヘッダが
電子メイルメッセージ中で使われていることを示すのではなく、
同じ ``スタイル'' のヘッダを表すのに使える名前であることを示します。
様々な MIME 仕様が定義しているヘッダに対しても使います。
ヘッダ名の表現方法は、実際に通常使われているのと同じ方法で入力しなくては
なりません。また、複数の用法があり、いずれも広く使われている場合には、
キャメル形式 (camel-casting) を優先します。ヘッダ名の後ろに続くコロンは
含めてはなりません。
例:
\mailheader{Content-Type}。
- \makevar
{name}
-
make における変数名です。
- \manpage
{name}{section}
-
Unix マニュアルページへの参照です。
- \member
{name}
-
オブジェクトのデータ属性名です。
- \method
{name}
-
オブジェクトのメソッド名です。name にはメソッド名とその後ろに続く
丸括弧を入れねばなりません。ドット名表記を使えます。
- \mimetype
{name}
-
MIME タイプの名前か、 MIME タイプの要素
(メジャータイプはマイナータイプのいずれか) の名前です。
- \module
{name}
-
モジュールの名前です: ドット名表記を使えます。
パッケージ名にもこれを使います。
- \newsgroup
{name}
-
Usenet のニュースグループ名です。
- \note
{text}
-
ある API について、ユーザがその API を一部でも利用する場合には知って
おかねばならないような特に重要な情報です。このマクロは注釈が終了する
場所を視覚的にマークしないので、段落の末尾の内容にせねばなりません。
text の内容は完全な文で書き、適切な区切りを入れねばなりません。
- \pep
{number}
-
Python Enhancement Proposal への参照です。このマクロは索引エントリを
生成します。 "PEP number" という出力を生成します;
HTML 出力の場合、テキストは指定された PEP のオンラインコピーに対する
ハイパーリンクになります。
- \plusminus
-
ある値が、指定した量に対して正負の値をとることを示すシンボルで、
通常はマイナス記号の上にプラス記号を置いて表します。例:
\plusminus 3%
- \program
{name}
-
実行可能形式のプログラム名です。プラットフォームによっては、
実行可能形式のファイル名とは異なる場合があります。特に、
Windows プログラムでは .exe (やその他の) 拡張子を
省略します。
- \programopt
{option}
-
実行可能プログラムのコマンドラインオプションです。
``短い'' オプションだけに使い、先頭にハイフンを入れてください。
- \longprogramopt
{option}
-
実行可能プログラムの長いコマンドラインオプションです。
このマクロは二つのハイフンから始まる長いオプション名だけに使います;
ハイフンを option に入れてはなりません。
- \refmodule
[key]{name}
-
\module に似ていますが、指定したモジュールに対する
ハイパーリンクを生成します。このマクロに対応する\declaremodule
は同じドキュメント内に入っていなければなりません。
\declaremodule がモジュール名とは異なるモジュールキーを
定義している場合、\refmodule マクロ内でも key として
指定せねばなりません。
- \regexp
{string}
-
正規表現をマークします。
- \rfc
{number}
-
Internet Request for Commments への参照です。適切な索引エントリを
生成します。テキスト "RFC number" を生成します; HTML 出力
では、テキストは指定した RFC のオンラインコピーに対するハイパーリンクに
なります。
- \samp
{text}
-
短いコード例で、\code で指定するには長すぎる場合に使います。
引用符記号を追加するので、テキストにスペースを入れてもかまいません。
- \shortversion
-
プリアンブルの\setshortversion マクロに指定されているような、
ドキュメントの対象となっているソフトウェアの ``短い'' バージョン番号です。
Python の場合、あるリリースに対する短いバージョン番号とは。
sys.version 値の最初の三文字です。例えば、バージョン 2.0b1
と 2.0.1 の短いバージョン番号はいずれも 2.0 になります。
全てのパッケージにこれが当てはまるわけではありません;
\setshortversion を使わなければ、このマクロは
空文字に展開されます。\version マクロも参照してください。
- \strong
{text}
-
強く強調されたテキストです; ボールドフォントで表現されます。
- \ulink
{text}{url}
-
URL で指定したターゲットを指すハイパーテキストリンクになりますが、
リンクテキストをドキュメントリソース中のタイトルにしてはなりません。
名前を使ってリソースを参照する場合には、\citetitle マクロを
使ってください。
全ての形式の出力が任意のハイパーテキストリンクをサポートしている
わけではありません。LaTeX 特有の多くの文字や、このマクロ特有の
文字を使った場合、たいてい正しい出力になりません。特に、
チルダ文字 ("~") は誤って処理されます; hex 形式の配列
にエンコードすればうまくいくので、チルダの代わりには"%7e" を
使ってください。
- \url
{url}
-
URL (または URN) です。 URL はテキストで与えます。
HTML や PDF の出力形式では、URL 文字列自体もハイパーリンクになります。
このマクロは、特定のタイトルを持たない外部リソースを参照する際に
利用できます; タイトルのあるリソースへの参照は \citetitle
マクロを使ってマークしてください。特殊文字に関する特別な扱いについては、
\ulink マクロの記述中のコメントを参照してください。
- \var
{name}
-
テキスト中で変数や仮引数の名前です。
- \version
-
プリアンブルの\release マクロに指定されているような、
ドキュメントの対象となっているソフトウェアのバージョン番号です。
\shortversion マクロも参照してください。
- \warning
{text}
-
ある API について、ユーザがその API を一部でも利用する場合には警告して
おかねばならないような重要な情報です。このマクロは注釈が終了する
場所を視覚的にマークしないので、段落の末尾の内容にせねばなりません。
text の内容は完全な文で書き、適切な区切りを入れねばなりません。
\note との違いは、セキュリティに関する情報の場合いは、
\warning の方が推奨されているという点です。
以下の二つのマクロは、あるリリースから別のリリースへの変更点に
関する情報を説明するときに使います。段落一つ程度で説明されている
ような内容に対して注釈を入れる場合には、その段落の末尾に一行空けて
記述します。複数の段落からなる場合には、説明全体の末尾に一行空けて
記述します。 \versionadded と\versionchanged の両方を
書かねばならない場合には、 \versionadded を先にしてください。
バージョン番号は、リリースされた順番に並んでいなければなりません。
また、これらのマクロは利用できる環境についての説明よりも前に置かねば
なりません。実際にマクロを書く場所は、説明としてわかりやすいように
しなければなりませんから、必要に応じて調整してもかまいません。
- \versionadded
[explanation]{version}
-
文章中で説明している機能がライブラリや C/API に追加された時の
Python のバージョン番号を示すために使います。
explanation は変更内容の短い 説明で、大文字から始まる
短い文章にします; 末尾のピリオドはフォーマット処理時に追加されます。
このマクロの対象がモジュール全体にわたる場合には、モジュールについて
説明している節の先頭に置き、他の文章より手前に来るようにしなければ
なりません。
- \versionchanged
[explanation]{version}
-
文章中で説明している機能が変更された (新たなパラメタの追加、
副作用の変化、など) 時の Python のバージョン番号を示すために使います。
explanation は変更内容の短い 説明で、大文字から始まる
短い文章にします; 末尾のピリオドはフォーマット処理時に追加されます。
通常、このマクロをモジュール全体に適用することはありません。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。
