9. 単語と句の印付け

Texinfoでは，様々な方法で単語や句に印を付けることが可能です．Texinfoフォー マッタは，テキストの強調の方法を決定するためにこの情報を使用します．例え ば，単語や句が，定義している事象，メタ構文の変数，またはプログラムで定義 されているシンボルであっても指定可能です．また，いくつかの異なる方法でテ キストを強調することも可能です．

9.1 定義，コマンド等を示す

Texinfoには，テキストの一部が言及しているものの種類を示すコマンドがあり ます．例えば，メタ構文の変数は@varで，コードは@codeで印 を付けられます．テキストの一部は，そのオブジェクトの種類を伝えるコマンド でラベルが付くので，Texinfoフォーマッタでそのようなテキストへの準備を変 更することは簡単です．(Texinfoは植字的な書式化言語というよりはむ しろ，意図的な書式化言語です．)

例えば，印刷されたマニュアルでは，コードは通常タイプライターのフォントで 図案化されます．@codeはTeXに，このテキストをこのフォントで植 字するよう伝えます．しかし，TeXのコードの強調を他のフォントを使用する よう変更することは簡単で，この変更はキーストロークの例を強調する方法に影 響しません．直接的な植字コマンドがファイルの本体で使用されていて，それを 変更したい場合，コードを変更して，他が変更されていないことを確かめるため， 全てのそれぞれの事象を調べる必要があります．

役に立つ強調コマンド

強調コマンドは，関数やファイル名のリストのような，ファイルからの便利な情 報を抽出するために使用することが可能です．例えば，Emacs Lisp(またはキー ボードマクロ)でのプログラムを書くために，指定されたコマンドで印が付いて いる単語と句が含まれているそれぞれの段落の後に，索引項目を挿入することも 可能です．まだ項目を作成していない場合，関数の索引を構築するためこれを行 うことが可能でしょう．

コマンドは様々な目的を満たします．

@code{sample-code}

プログラムの一部のリテラル例となるテキストを示します．

@kbd{keyboard-characters}

キーボード入力を示します．

@key{key-name}

キーボードのキーに対する慣習的な名前を示します．

@samp{text}

文字列のリテラル例となるテキストを示します．

@var{metasyntactic-variable}

メタ構文変数を示します．

@env{environment-variable}

環境変数を示します．

@file{file-name}

ファイル名を示します．

@command{command-name}

コマンド名を示します．

@option{option}

コマンドラインオプションを示します．

@dfn{term}

用語使用の紹介や定義を示します．

@cite{reference}

本の名前を示します．

@acronym{acronym}

頭文字を組み合わせた言葉を示します．

@url{uniform-resource-locator}

ワールドワイドウェブ(WWW)のユニフォームリソースロケータ(URL)を示します．

@email{email-address[, displayed-text]}

電子メールアドレスを示します．

9.1.1 @code{sample-code}

プログラムの一部と，全体が構文的なトークンからなるテキストを示すため， @codeコマンドを使用してください．カッコでテキストを囲ってくださ い．

このため，@codeをプログラム内部の式，プログラムで使用している変 数や関数の名前，またはプログラム言語のキーワードに対して使用すべきです．

Texinfoのようなプログラム言語に似ている言語のコマンド名に対して @codeを使用してください．例えば，@codeと@sampは， Texinfoソースファイルで，それぞれ`@code{@@code}'と `@code{@@samp}'と書くことで生成されます．

文の最初に現れるとき，@codeコマンドの中で単語の大文字小文字を変 えるのは正しくありません．ほとんどのコンピュータ言語は大文字小文字の違い を識別します．例えばCでは，Printfはprintfの識別子と異なり， それはおそらくスペルミスです．大文字小文字の区別をしない言語でも，異なる 方法で綴られた識別子を見ると人間の読者は混乱します．一つの綴りを選び，そ れを常に使用してください．全てが小文字で書かれたコマンド名で文を開始した くない場合，文の配置替えをするべきです．

印刷されたマニュアルでは，@codeでTeXは引数をタイプライターフェ イスのフォントで植字します．Infoファイルでは．Info書式化コマンドはシング ルクォーテーションマークでテキストの周りを囲みます．

例えば，以下のようにします．

The function returns @code{nil}.

印刷されたマニュアルで，これは以下を生成します．

The function returns nil.

@codeを使用しないほうが好ましい状況は，以下のものです．

• lsのようなシェルコマンド名(@commandを使用してください)．

• `-c'のようなシェルオプション単独のとき(@optionを使用してくだ さい)．

• また，シェルコマンド全体は，@codeより@sampを使用して書い た方が良く見えます．この場合，規則はより喜ばしい書式を選択するためです．

• TEXINPUTSのような環境変数(@envを使用してください)．

• 構文トークンより短い文字列．例えば，Emacs Lisp関数のgoto-charの名 前の一部の`goto-ch'に関して書く場合，@sampを使用すべきです．

• 一般的に，トークンで使用されている文字に関して書く場合です．例えば，関数 名で使用可能な文字や印刷可能なシンボルを説明しているとき，@code を使用しないでください．(@sampを使用してください．)また，入力が プログラム言語のような言語で書かれていない場合，プログラムの入力と考えら れるテキストに印を付けるために@codeを使用すべきではありません． 例えば，GNU Emacsのキーストロークコマンドに対して@codeを使用すべ きではありませんが(代わりに@kbdを使用してください)，キーストロー クコマンドが呼び出すEmacs Lispの関数名に対し@codeを使用してもか まいません．

@command，@option，そして@envは比較的最近導入さ れたので，@codeや@sampをコマンド名，オプション，そして環 境変数に使用することも可能です．新しいコマンドでより正確に印付けを表現で きますが，より古いコマンドの使用でも実害は無く，もちろん長期存続のマニュ アルはそうしています．

9.1.2 @kbd{keyboard-characters}

ユーザが入力する文字に対し@kbdコマンドを使用してください．例えば， 文字M-aを記述するため，以下のように書いてください．

@kbd{M-a}

文字M-x shellを記述するため，以下のように書いてください．

@kbd{M-x shell}

@kbdコマンドはInfoでは@codeと同じ効果がありますが，印刷 されたマニュアルではデフォルトで異なるフォント(通常のタイプライターの代 わりに傾いたタイプライター)を生成し，そのため，ユーザはこれらのコンピュー タの出力と，入力として仮定される文字とを区別可能です．

@kbdの使用法がマニュアル間で異なるので，@kbdinputstyleコ マンドでフォント切替えの制御が可能です．このコマンドはInfo出力で効果があ りません．このコマンドを行の最初で，引数として一単語で以下の一つを書いて ください．

`code'

常に@kbdに対し@codeと同じフォントを使用します．

`example'

@exampleとそれに似た環境のみで，@kbdに対し異なるフォント を使用します．

`distinct'

(デフォルトで)常に@kbdに対し異なるフォントを使用します．

@kbdコマンドのカッコの中に他の@-コマンドを埋め込むことが可能で す．例えばここで，より冗長に記述すると，"`r'を押し，RETを押 してください"となるコマンドを記述した例があります．

@kbd{r @key{RET}}

これはr RETを生成します．

また，入力した文字を書き出すために@kbdコマンドを使用することも可 能です．例えば，以下のようにします．

To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.

これは以下を生成します．

To give the logout command, type the characters l o g o u t RET.

(また，この例は明確にするためスペースを加えることが可能だということも示 しています．実際にスペース文字を入力文字の一つとして述べたい場合，そのた めに@key{SPC}を書いてください．

9.1.3 @key{key-name}

@keyコマンドをキーボード上のキーの慣習名に対し以下のように使用し てください．

@key{RET}

入力された文字の並びが一つ以上の名前で記述されたキーを含むとき， @keyコマンドを，@kbdコマンドの引数内部で使用可能です．

例えば，入力するC-x ESCを生成するために，以下のようにします．

@kbd{C-x @key{ESC}}

推奨されるキーの名前のリストは以下のものがあります．

SPC

スペース

RET

リターン

LFD

Linefeed(しかし，最近のほとんどのキーボードはLinefeedキーが無いので，この 文字C-jを呼ぶ方がいいでしょう)．

TAB

タブ

BS

バックスペース

ESC

エスケープ

DEL

デリート

SHIFT

シフト

CTRL

コントロール

META

メタ

修飾キー名の`meta'や`ctrl'のような単語を扱う細別手法もあります． Meta-aのような，修飾キーが使用されている文字を記述するとき， @kbdコマンドを単独で使用してください．@keyコマンドを使用 しないでください．しかし，修飾キーを単独で記述するときは@keyコマ ンドを使用してください．例えば，Meta-aを生成するため `@kbd{Meta-a}'と書き，METAを生成するため `@key{META}'と書いてください．

9.1.4 @samp{text}

ファイル，文字列，パターンなどの内部の文字の並びの例や`sample'のリテラル となるテキストを示すため，@sampコマンドを使用してください．テキ ストをカッコで囲んでください．Infoファイルと印刷されたマニュアルの両方で， シングル引用符の中にで引数が現れます．さらに，等幅フォントで印刷されます．

To match @samp{foo} at the end of the line,
use the regexp @samp{foo$}.

これは以下を生成します．

To match `foo' at the end of the line, use the regexp `foo$'.

単一の文字を記述するときはいつも，@kbdや@keyがより適して いない限り@sampを使用すべきです．また，Cの記述全体やシェルコマン ド全体に対し@sampを使用することも可能です．この場合， @sampは@codeより良く見えます．基本的に，@sampは @code，@kbd，または@keyでカバーされていないあら ゆるものに対する入れものです．

指定した文字列の一部の場合のみ，句読点をカッコ内に含めてください．句読点 が文字列の周りにある英語のテキストの一部の場合，カッコの外に句読点を書い てください．例えば以下の文章では，カンマとピリオドはカッコの外側に置きま す．

In English, the vowels are @samp{a}, @samp{e},
@samp{i}, @samp{o}, @samp{u}, and sometimes
@samp{y}.

これは以下を生成します．

In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.

9.1.5 @verb{<char>text<char>}

文字の並びをそのまま出力するために，@verbコマンドを使用してくだ さい．

LaTeXの\verbコマンドのように，テキストそのままを，ユニークな分 離文字を使用して引用符で囲むことが可能です．囲まれているテキストは自身に はカッコの中の分離文字も含まれます．テキストは固定幅フォントで出力されま す．

How many @verb{|@|}-escapes does one need to print this
@verb{.@a @b @c.} string or @verb{+@'e?`!`{}\+} this?

以下を生成します．

How many @verb{|}-escapes does one need to print this
@verb{.@a @b @c.} string or these @verb{+é?`{}!`\+} this?

これは，引数が通常のTexinfoのテキストになる@samp(前のセクション を参照してください)と比較して，文字@{}は特別です． @verbを用いた場合，選択した分離文字以外，特別な例外はありません．

9.1.6 @var{metasyntactic-variable}

メタ構文変数を示すため，@varコマンドを使用してください．メ タ構文変数(metasyntactic variable)は，テキストの一部と同類のものを意味 するものです．例えば，メタ構文変数を関数に渡される引数を記述するため関数 のドキュメントで使用すべきです．

プログラム言語で，特定の変数の名前に対し@varを使用しないでくださ い．これらはプログラムの特別な名前なので，それに対しては@codeが 正しいものです(see section 9.1.1 @code{sample-code})．例えば，Emacs Lisp変数 texinfo-tex-commandはメタ構文変数ではありません．それは， @codeを使用することで正確に書式化されます．

環境変数に対しても@varを使用しないでください．それに対しては @envが正しいものです(次のセクションを見てください)．

Infoでの@varの効果は，引数の文字を全て大文字に変更します．印刷さ れたマニュアルとHTML出力では引数は傾いて印刷されます．

例えば，以下のようにします．

To delete file @var{filename},
type @samp{rm @var{filename}}.

以下を生成します．

To delete file filename, type `rm filename'.

(@varは@code，@samp，@fileなどの間に現す ことができることに注意してください．)

メタ構文変数は，スペース以外全て小文字で書き，読みやすくするためハイフン を使用してください．このため，Texinfoマニュアルの初め方を表現するTexinfo ソースは以下のようになります．

\input texinfo
@@setfilename @var{info-file-name}
@@settitle @var{name-of-manual}

これは以下を生成します．

\input texinfo
@setfilename info-file-name
@settitle name-of-manual

ドキュメント形式によっては，メタ構文変数は山カッコで表示するものもあり， 以下がその例です．

..., type rm <filename>

しかし，それはTexinfoが使用する形式ではありません．(もちろん，そうしたい 場合，`texinfo.tex'ソースを編集して，Info書式化コマンドを <...>書式で出力させることもできます．)

9.1.7 @env{environment-variable}

GNUを含め，多くのオペレーティングシステムで使用される環境変数を示すため， @envコマンドを使用してください．メタ構文変数に使用しないでくださ い．代わりに@varを使用してください(前のセクションを参照してくだ さい)．

@envの効果は@codeと同じです．例えば，以下のようにします．

The @env{PATH} environment variable ...

The PATH environment variable ...

9.1.8 @file{file-name}

ファイル，バッファ，またはディレクトリ名や，Infoでのノード名となるテキス トを示すため，@fileコマンドを使用してください．また，ファイル名 の接尾子にも使用可能です．プログラム言語のシンボルに対し@fileを 使用しないでください．@codeを使用してください．

現在，@fileの効果は@sampと同じです．例えば以下のようにし ます．

The @file{.el} files are in
the @file{/usr/local/emacs/lisp} directory.

以下を生成します．

The `.el' files are in the `/usr/local/emacs/lisp' directory.

9.1.9 @command{command-name}

lsやccのようなコマンド名を示すため，@command を使用してください．

@commandの効果は@codeと同じです．例えば，以下のようにし ます．

The command @command{ls} lists directory contents.

The command ls lists directory contents.

`Emacs'や`Bison'のような新しい英単語にしたい場合，@commandを使用 せず，通常のテキストのフォントでプログラム名を書くべきです．

`ls -l'のようなシェルコマンドの呼び出し全体を書くとき，自分で判断し て@sampまたは@codeのどちらかを使用すべきです．

9.1.10 @option{option-name}

コマンドラインオプションを示すため，@optionコマンドを使用してく ださい．例えば， `-l'や，`--version'や， `--output=filename'です．

@optionの効果は@sampと同じです．例えば以下のようにします．

The option @option{-l} produces a long listing.

The option `-l' produces a long listing.

表では，オプションを@codeの中に書くと，より喜ばしい効果を生成し ます．

9.1.11 @dfn{term}

技術用語の使用の紹介や定義を識別するため，@dfnコマンドを使用して ください．もう一度使用する用語や読者が知っておくべき用語の紹介を意図した 引用部分でのみ，このコマンドを使用してください．最初に用語について述べる ちょっとした記述は@dfnに値しません．コマンドは印刷されたマニュア ルでイタリック体を生成し，Infoファイルでは2重引用符を生成します．例えば 以下のようにします．

Getting rid of a file is called @dfn{deleting} it.

以下を生成します．

Getting rid of a file is called deleting it.

一般的な規則として，用語の発生の定義を含む文は用語の定義にすべきです．文 はその定義を明示的にする必要はありませんが，定義情報を含めるべきです -- それで意味がはっきりします．

9.1.12 @cite{reference}

Infoファイルの仲間にはない本の名前に対し@citeコマンドを使用して ください．コマンドは印刷されたマニュアルでイタリック体を生成し，Infoファ イルでは引用符を生成します．

本がTexinfoで書かれている場合，読者はInfoでそのような参照を簡単に追うこ とが可能なので，相互参照を使用してください．@xref{xref, , @xref}.

9.1.13 @acronym{acronym}

`NASA'のように全て大文字で書かれている省略に対し， @acronymを使用してください．省略は`@acronym{NASA}'のよう にカッコ内に一つの引数で与えられます．形式の問題や特定の省略のため， `@acronym{F.B.I.}'のようにピリオドを使用した方が良いかもしれませ ん．

TeXとHTMLでは，引数は傾いた小さなフォントサイズで印刷されます．Infoや プレーンテキスト出力では，このコマンドは何も変更しません．

9.1.14 @url{uniform-resource-locator}

ワールドワイドウェブ(WWW)のユニフォームリソースロケータ(URL)を示すため， @urlコマンドを使用してください．これは，@file， @var等に似ていて，純粋にマークアップのためのものです．それはHTML 形式でたどることが可能なリンクを生成しません(そのためには@uref を使用してください．see section @uref)．実際には存在しないURL に対して役に立ちます．例えば，以下のようにします．

For example, the url might be @url{http://example.org/path}.

それは，以下を生成します．

For example, the url might be http://example.org/path.

9.1.15 @email{email-address[, displayed-text]}

電子メールアドレスを示すため@emailコマンドを使用してください．そ れは引数として一つの必須のアドレスと，一つの追加引数で表示するテキストをと ります(デフォルトではアドレス自身になります)．

InfoとTeXでは，アドレスは山カッコで表示され，存在する場合は表示テキス トが前に付きます．HTML出力では，@emailは通常メール作成ウィンドウ を生成する`mailto'リンクを生成します．例えば，以下のようにします．

Send bug reports to @email{bug-texinfo@@gnu.org},
suggestions to the @email{bug-texinfo@@gnu.org, same place}.

Send bug reports to bug-texinfo@gnu.org,
suggestions to the same place.

9.2 テキストの強調

通常Texinfoは，テキストで単語が属するカテゴリに従って印付けされた単語に 対しフォントを変更します．例えば@codeコマンドです．ほとんどの状 況で単語に印を付ける方法が最善です．しかし，カテゴリを示さずにテキストを 強調したいときもあります．Texinfoにはこのための二つのコマンドがあります． またTexinfoには，TeXがテキストを植字するときのフォントを指定するコマ ンドもいくつかあります．これらのコマンドはInfoでは効果が無く，その中の一 つ@rコマンドだけ，通常使用されます．

9.2.1 @emph{text}と@strong{text}

@emphと@strongコマンドは，強調のためのものです． @strongがより強調します．印刷物で，@emphはitalics を生成し，@strongはboldを生成します．

例えば，以下のようにします．

@quotation
@strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
files in the directory.
@end quotation

以下を生成します．

    *Caution*: `rm * .[^.]*' removes _all_
    files in the directory.

@strongコマンドは，前の例での単語`Caution'のような，効果が印刷要 素となるマーク以外では，滅多に使用されません．

Info出力では，@emphはアンダースコア(`_')でテキストを囲み， @strongはテキストの周りにアスタリスクを書きます．

注意:@strongを単語`Note'で使用しないでください． Infoは相互参照との組み合わせと勘違いします．代わりに，Please noteやCautionのような句を使用してください．

9.2.2 @sc{text}:小さな大文字フォント

テキストを，印刷物とHTMLでA SMALL CAPS FONTに設定し，Infoファイルで 大文字に設定するため，`@sc'コマンドを使用してください．(可能な場合) 小さい大文字にしたいテキストを以下のように小文字でカッコの間に書いてくだ さい．

The @sc{acm} and @sc{ieee} are technical societies.

これは以下を生成します．

The ACM and IEEE are technical societies.

TeXは，文字が`ページからはみ出る'ことを避けるように，小さい大文字フォ ントで植字します．これは，小さい大文字のテキストを全て大文字にするより読 みやすくします．しかし通常は，どこでも大文字小文字を混ぜて使用する方が良 いでしょう．Info書式化コマンドは，全ての小さい大文字のテキストを大文字に 設定します．HTMLでは，テキストは大文字で小さいフォントで表現されます．

@scコマンドのカッコ内のテキストが大文字の場合，TeXはフルサイ ズの大文字で植字します．今までそうしている場合，@scで全て大文字 のテキストに印を付けるのは無駄なので，makeinfoがそのような使用 法に警告する場合は，省略してフルサイズの大文字を使用してください．

また，ATO(`abort to orbit'を意味するNASA単語)のような専門用語 に対し小さな大文字フォントを使用することも可能です．

Lispプログラムで使用される単語CDRのような専門用語で小さな大文字フォ ントを使用することには微妙な点があります．この状況では，単語がリスト(リ ストのCDR)の二番目のものとそれに続く要素を参照するときは小さな大文 字フォントを使用すべきですが，単語が同じ綴りのLisp関数を参照するときは `@code'を使用すべきです．

9.2.3 Infoではなく印刷時のフォント

Texinfoには，Infoでは効果が無く印刷されたマニュアルでフォントの変更を指 定する，四つのフォントコマンドを提供しています．@iはitalicフォ ント(TeXのバージョンによっては傾いたフォントが使用される)を要求し， @bはboldフェイスを要求し，@tは@codeで使用さ れるタイプライター形式のフォントfixed-widthを要求し，そして， @rはテキストの印刷での通常フォントのromanフォントを要求しま す．すべての四つのコマンドは，それに続くカッコに囲まれた引数に適用します．

@rコマンドのみがよく使用されます．例としてのプログラムで，コード コメントを等幅フォントからローマンフォントに変更するため，@rコマ ンドを使用することが可能です．これは，印刷された出力で見ためが良くなりま す．

例えば，以下のようにします．

@lisp
(+ 2 2)    ; @r{Add two plus two.}
@end lisp

以下を生成します．

(+ 2 2)    ; Add two plus two.

可能な場合，他の三つのフォントコマンドの使用を避けるべきです．その一つを 使用する必要がある場合，Texinfo言語ではおそらくギャップが生じます．