REFER

Section: User Commands (1)
Updated: 6 August 2001
Index JM Home Page

名称

refer - groff のための参考文献目録プリプロセッサ

書式

refer [ -benvCPRS ] [ -an ] [ -cfields ] [ -fn ] [ -ifields ] [ -kfield ] [ -lm,n ] [ -pfilename ] [ -sfields ] [ -tn ] [ -Bfield.macro ] [ filename... ]

コマンドラインオプションとパラメータの間に、空白を置くことが可能です。

解説

本ファイルでは groff ドキュメントフォーマッティングシステムの一部である GNU バージョンの refer について記述します。 refer は .[ と .] で囲まれた引用として解釈される行と、 .R1 と .R2 で囲まれた引用の処理方法を記述したコマンドとして解釈される行を除き、 filename... の内容を標準出力にコピーします。

各々の引用では参考文献を指定します。引用では、ある参考文献にのみ含まれるキーワードの集合を与えることによって、その参考文献を図書目録データベースから指定できます。また、引用の中でデータベースレコードを指定することによっても参考文献を指定できます。これらの方法を組み合わせることも可能です。

各々の引用において refer はテキストの中にマークを作成できます。このマークは色々な方法でテキストや他のラベルから区別されるいくつかのラベルから構成されます。各引用における参考文献をマクロパッケージを使ってフォーマットして出力するための groff コマンドを出力することもできます。そのためには refer の出力は適切なマクロパッケージを使って処理されなければなりません。 -ms と -me はいずれも適切なマクロです。引用の参考文献をフォーマットするコマンドを引用の直後に出力することも、参考文献を蓄積して後でコマンドを出力することもできます。参考文献を蓄積した時、同じ参考文献が複数から引用されている場合には、参考文献は 1 つにまとめてフォーマットされます。

GNU refer の新しい機能として .R1 と .R2 の間の行はコマンドとして解釈されます。この機能を使用して作成されたドキュメントは、ドキュメントの先頭に

.de R1
.ig R2
..

の行を追加することにより UNIX refer でも処理できます。この指定によって troff は .R1 と .R2 の間をすべて無視します。このオプションによっていくつかのコマンドと同等の効果を得ることができます。これらのオプションは主に Unix refer との互換性のためにサポートされているものです。通常はコマンドを使った方が便利です。

refer は refer の出力を読むコマンドによって生成されるメッセージの中のファイル名と行番号が正しくなるように .lf 行を生成します。入力が soelim (1) のようなコマンドによって前処理されている場合でも、メッセージ中のファイル名と行番号と生成される .lf 行が正確になるように .lf で始まる行も解釈します。

オプション

ほとんどのオプションには同等なコマンドがあります (これらのコマンドについては コマンド セクションの説明を参照して下さい)。

-b: no-label-in-text; no-label-in-reference
-e: accumulate
-n: no-default-database
-C: compatible
-P: move-punctuation
-S: label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
-an: reverse An
-cfields: capitalize fields
-fn: label %n
-ifields: search-ignore fields
-k: label L~%a
-kfield: label field~%a
-l: label A.nD.y%a
-lm: label A.n+mD.y%a
-l,n: label A.nD.y-n%a
-lm,n: label A.n+mD.y-n%a
-pfilename: database filename
-sspec: sort spec
-tn: search-truncate n

これらのオプションは以下のコマンドと同等です。ただし、通常の方法のかわりにコマンド行で指定されるファイル名が bibliography コマンドへの引数であるように処理されます。

-B: annotate X AP; no-label-in-reference
-Bfield.macro: annotate field macro; no-label-in-reference

以下のオプションには同等なコマンドはありません。

-v: バージョン番号を表示します。
-R: .R1 / .R2 で始まる行を認識しません。

使用法

図書目録データベース

図書目録データベースは 1 行以上の空白行で区切られたレコードからなるテキストファイルです。各レコードではフィールドは % で始まる行で開始します。各フィールドには % に続く 1 文字の名称があります。フィールドの名称には大文字か小文字のみを使うのが最良の方法です。フィールドの名称の後には正確に 1 つのスペースが続かなければなりません。空のフィールドは無視されます。各フィールドの慣例的な意味は次の通りです。

A: 作者の名前。名前の末尾に Jr. のような肩書が含まれる場合はコンマでラストネームと区切られていなければなりません。 A フィールドは複数回現れても構いません。出現する順番は意味を持ちます。 A フィールドか Q フィールドは常に指定するのが良いでしょう。
B: ある本の一部である記事において、その本のタイトルです。
C: 出版社の所在地 (都市) です。
D: 出版された日付です。出版年に略称を使用してはいけません。もし出版月を指定する場合は数字による月ではなく、月名を使わなければなりませんが、最初の 3 文字を指定すれば十分です。 D フィールドは常に指定するのが良いでしょう。ただし、出版の日付が分からなければ in press や unknown のような値を使うこともできます。
E: ある本の一部である記事において、その本の編集者の名前です。出版作業が著者のない編集だけのものであった場合、編集者の名前を A フィールドで指定し、 , (ed) または , (eds) を最後の著者の後に指定しなければなりません。
G: 米国政府注文番号です。
I: 出版者 (発行人) です。
J: 定期刊行物の記事における、その刊行物の名称です。
K: 検索に使われるキーワードです。
L: ラベルです。
N: 定期刊行物の発行番号です。
O: その他の情報です。これは通常参考文献の末尾に印刷されます。
P: ページ番号です。ページ番号の範囲は m - n で指定できます。
Q: 著者が個人でない場合の著者の名称です。これは A フィールドがない場合にのみ使用されます。 Q フィールドは 1 つのみ使うことができます。
R: 技術報告書番号です。
S: シリーズの名称です。
T: タイトルです。本や定期刊行物中の記事ではこれは記事のタイトルとなります。
V: 定期刊行物もしくは本のボリューム番号です。
X: 注釈です。

A と E を除くすべてのフィールドで、あるレコードに複数の特定のフィールドがある場合、最後のフィールドのみが使用されます。

アクセント文字列はアクセントをつける文字に引き続いて指定されなければなりません。これは AM マクロは -ms マクロとともに使用しなければならないことを意味します。アクセント文字列は引用符で囲んではいけません。また、 \ は 2 つでなく 1 つのみ使って下さい。

引用

引用のフォーマットは

.[opening-text
flags keywords
fields
.]closing-text

となります。

opening-text と closing-text と flags のコンポーネントは省略可能です。 keywords か fields のいずれか 1 つのコンポーネントを指定する必要があります。

keywords コンポーネントは keywords に含まれる全ての単語を含む参考文献を文献データベースから検索するために指定します。もし複数の参考文献が見つかった場合はエラーとなります。

fields コンポーネントは参考文献の中で指定されるものを置き換えるか付け加えるための追加フィールドを指定します。参考文献が蓄積される設定で、 keywords コンポーネントが空でなければ、追加フィールドはある特定の参考文献が引用されている最初の部分においてのみ指定されなければならず、その参考文献を引用している全ての部分に適用されます。

opening-text と closing-text コンポーネントは bracket-label コマンドにおいて指定される文字列の代わりにラベルを囲むために使われる文字列を指定します。これらのいずれもが空でなければ、 bracket-label コマンドで指定されている文字列は使われません。この処理は [ と ] フラグを使って置き換えることができます。これらのコンポーネントの前と後につくスペースは意味を持つことに注意して下さい。

flags コンポーネントはここでの引用の扱いを変更するためのアルファベット以外の文字のリストです。 Unix refer はこれらのフラグをキーワードの一部として処理しますが、それらはアルファベットでないため無視します。以下のフラグが現在認識されるものです。

#: これは short-label コマンドによって指定されるラベルを label コマンドで指定されるものの代わりに使用することを指示します。もしショートラベルが指定されなければ、通常のラベルが使用されます。普通はショートラベルは auther-date ラベルに使用され、日付とおそらくは曖昧さが取り除かれた文字から構成されます。ここで、 # はラベルの数字によるタイプを示唆するものと考えられます。
[: bracket-label コマンドの中で指定される最初の文字列が opening-text の前に置かれます。
]: bracket-label コマンドの中で指定される 2 番目の文字列が closing-text の後に置かれます。

opening-text と closing-text の中に括弧を含めるのではなく、 [ と ] フラグを使うことの 1 つの利点は bracket-label コマンドで変更するだけでドキュメントの中で使っている括弧のスタイルを変更できることです。もう 1 つの利点として、これらのフラグを使うことによって引用のソートとマージを禁止する必要がないことがあげられます。

もしラベルがテキスト中に挿入されるべきものであれば、それは .[ 行の前の行に挿入されます。そのような行がない場合には .[ の前に余分の行が挿入されて警告が表示されます。

複数の参考文献に対する引用を作成する特別の表記法はありません。ただ引用を 1 つの参考文献につき 1 つずつ連続して使用します。引用の間には何も入れないで下さい。全ての引用に対するラベルは最初の引用の前の行に付加されます。ラベルはまたソートしたり、マージしたりすることもできます。ラベルの表記法 <> とコマンド sort-adjacent-labels と abbreviate-label-ranges の説明を参照して下さい。ラベルは引用に空でない opening-text か closing-text がある時にはマージされません。しかし、 opening-text が伴わず [ フラグを使った引用がその直後に続く、 closing-text を伴わない ] フラグを使った引用のラベルは最初の引用の opening-text か次の引用の closing-text が空でない場合においても、ソートとマージを行なうことができます。 (もしこれを行ないたくない場合は、最初の引用で closing-text を \& としてください。)

コマンド

コマンドは .R1 で始まる行と .R2 の間に指定されます。これらの行は -R オプションを使うことによって認識されないようにできます。 .R1 行が認識された時、すべての蓄積されている参考文献は消去されます。 .R1 行と .R2 行およびこれらの間に指定されたものはすべて出力されません。

コマンドは改行か ; によって区切られます。 # からその行の最後まではコメントとなります (しかし、改行自身は改行としてあつかわれます）。各コマンドはワードに分割されます。ワードはスペースかタブによって区切られます。 s で始まるワードは次の s (ただしもう 1 つの s が直後にないもの) までがワードとして扱われます。もし、次の s がない場合にはその行の最後までがワードとなります。 s で始まるワード中の s のペアはひとつの s として扱われます。 s の中では # と ; は認識されません。行は末尾に \ をつけることによって継続できます。ただし # の後の場合は継続されません。

* でマークされた各コマンド name には name の効果を打ち消す否定コマンド no-name があります。例えば、 no-sort コマンドは参考文献をソートしないことを指定します。否定コマンドは引数を取りません。

以下の説明で各引数はひとつのワードとなります。 field はフィールドの名前となる 1 文字の小文字または大文字です。 fields はそのような文字のシーケンスです。 m と n は非負の数字です。 string は任意の文字列です。 filename はファイル名です。 u+2n

abbreviate* fields string1 string2 string3 string4 fields のファーストネームを短縮形にします。頭文字ともう 1 つの頭文字の間には string1 が挿入されます。ラストネームとの間には string2 が挿入され、その他のもの ( von や de のようなもの) との間には string3 が挿入されます。これらのストリングのデフォルトはピリオドにスペースが続いたものとなります。ハイフンで区切られたファーストネームの中で、名前の最初の部分の頭文字は string4 (デフォルトはピリオド) によってハイフンと分離されます。省略形に起因する曖昧さについては特に考慮していません。名前はソートする前およびラベルが構築される前に省略形にされます。

abbreviate-label-ranges* string

連続した参考文献を参照する 3 つ以上の隣接するラベルは、最初のラベル string 最後のラベルの順からなる 1 つのラベルに省略されます。これは主に数字ラベルにおいて便利です。 string が省略された場合のデフォルトは - です。

accumulate*

各参考文献を出現するたびに書き出すのではなく、参考文献を蓄積していきます。蓄積された参考文献はすべての入力ファイルが処理され .R1 行が認識された後に、

.[
$LIST$
.]

の形式の参照が指定された時に書き出されます。

annotate* field string

field は注釈です。注釈は参考文献の最後に

.string

の行の後にパラグラフとして印刷されます。 macro が省略されるとデフォルトの AP となります。もし、 field も省略されるとデフォルトの X となります。注釈になれるフィールドは 1 つのみです。

articles string...

string... は定冠詞もしくは不定冠詞であり、ソートされる時にはフィールド T の最初では無視されなければなりません。初期状態では the と a と an が冠詞として認識されます。

bibliography filename...

図書目録データベース filename... に含まれる全ての参考文献を書き出します。

bracket-label string1 string2 string3

テキスト中で、各ラベルを string1 と string2 で囲みます。 string2 の直後に string1 が現れた場合は string3 に置き換えられます。デフォルトでは

bracket-label \*([. \*(.] ", "

となります。

capitalize fields

fields を大文字とそれに続く小文字に変換します。

compatible*

スペースや改行以外の文字が次に続く場合でも .R1 と .R2 を認識します。

database filename...

図書目録データベース filename... を検索します。各々の filename について、もし indxbib(1) によって生成されたインデックス filename.i が存在すれば、それが代わりに検索されます。各インデックスは複数のデータベースをカバーできます。

date-as-label* string

string はラベルを構成した後にフィールド D を置き換える文字列を指定するラベル式です。ラベル式の説明については ラベル式 の項を参照して下さい。このコマンドは参考文献リストの中で明示的なラベルは使いたくないが、何らかの方法で日付を修飾することによって曖昧さを取り除きたい場合に便利です。通常、テキスト中で使用されているラベルは作者と日付の組み合わせになります。ほとんどの場合、 no-label-in-reference コマンドも使う必要があります。例えば、

date-as-label D.+yD.y%a*D.-y

は参考文献中のフィールド D の年の部分に曖昧さを取り除く文字を追加します。

default-database*

デフォルトのデータベースを検索します。これはデフォルトの動作であり、このコマンドの否定バージョンが有用です。 refer は検索を行なう必要が最初に出てきた場合、デフォルトのデータベースを検索するべきかどうかを決定します。そのため no-default-database コマンドを有効とするためには、それ以前に指定しておく必要があります。

discard* fields

参考文献が読み込まれた時、 fields を無効とします。 fields の文字列の定義は出力されません。初期状態では fields は XYZ となっています。

et-al* string m n

ラベル式における式 @ の評価での et al の使い方を制御します。著者のシーケンスを明確にするために必要な著者の数を u 、著者の合計が t とすると、最後の t-u の著者が string によって置換され、 t-u が m より小さくなく、 t が n より小さくないようになります。デフォルトでは

et-al " et al" 2 3

となります。

include filename

filename をインクルードし、その内容をコマンドとして解釈します。

join-authors string1 string2 string3

これはどのように作者を連結するかを指定します。ちょうど 2 人の作者がある場合、 string1 によって連結されます。 2 人より多い作者がある場合、最後の 2 人を除いた作者は string2 で連結され、最後の 2 人の作者は string3 で連結されます。もし string3 が省略されると、デフォルトは string1 となります。もし string2 も省略されると、デフォルトは string1 となります。例えば、

join-authors " and " ", " ", and "

は作者の連結をデフォルトの方法に戻します。

label-in-reference*

参考文献を出力する時に、文字列 [F を参考文献のラベルに定義します。これはデフォルトの動作です。このコマンドの否定バージョンが有用です。

label-in-text*

各参考文献においてテキスト中のラベルを出力します。ラベルは bracket-label コマンドに記述されているようにそれを囲むテキストと分離されます。これはデフォルトの動作です。このコマンドの否定バージョンが有用です。

label string

string はどのように各参考文献にラベルをつけるかを記述するラベル式となります。

separate-label-second-parts string

2つの部分からなるラベルをマージする時、2 番目のラベルの 2 番目の部分を string で最初のラベルと分離します。ラベル式については <> のラベル式の説明を参照して下さい。

move-punctuation*

テキストにおいてラベルの後の行末の句読点を移動します。ラベルに肩文字の数字を使っていなければ、このコマンドを使うといいでしょう。

reverse* string

名前が string 中にあるフィールドを逆にします。各フィールド名の後にはいくつのフィールドが逆にされるかを示す数が指定されます。フィールドにこの数が指定されなければ、そのフィールドは全て逆になります。

search-ignore* fields

インデックスが存在しないデータベースでキーを検索している際に、 fields の内容を無視します。初期状態ではフィールド XYZ が無視されます。

search-truncate* n

キーの最初の n 文字が与えられることのみを要求します。実際にデータベース中で与えられたキーを検索する時には n とキーの長さの大きい方の長さに切られます。初期状態では n は 6 です。

short-label* string

string はラベルのもう 1 つの (通常は短縮形の) スタイルを指定するラベル式です。これは # フラグが引用で与えられている時に使われます。 author-date スタイルのラベルを使う時、作者は文脈から明らかに識別できることがあり、ラベルでは作者を省略したいことがあります。通常、 short-label コマンドは日付と (多分) 明確な文字のみを含むラベルを指定するために使用されます。

sort* string

string に従って参考文献をソートします。参考文献は自動的に累積されます。 string はフィールド名のリストであり、各フィールド名にはソートに使われる名前にいくつのフィールドがあるかを示す数字が続きます。 + を名前のついた全てのフィールドを使うことを示すために使うことができます。また、 . を参考文献が (一時的な) ラベルを使ってソートされることを示すために使うこともできます。 ( ラベル式 のセクションで一時的なラベルの概念について説明しています。)

sort-adjacent-labels*

参考文献リスト中での位置に従って、テキスト中の隣接しているラベルをソートします。このコマンドは通常は abbreviate-label-ranges コマンドが与えられている時か、ラベル式に <> 式が含まれている時に使用するべきです。これは参考文献が累積されていないと影響がありません。

ラベル式

ラベル式は通常もしくは一時的に評価できます。通常評価の結果は出力に使われます。一時的評価の結果は 一時的ラベル と呼ばれ、通常評価でラベルを明確にする必要がある情報を集めるために使われます。 date-as-label と short-label コマンドで指定されるラベル式は一時的には評価されません。通常評価と一時的評価は @ と * と % の式を除いた全てのタイプの式で同じです。以下の説明は特に指定された場合を除き通常評価に適用されます。

field
field n field の n 番めの部分です。 n が省略された場合はデフォルトは 1 となります。
'string': string 中の文字は文字通り解釈されます。
@: 全ての作者を join-authors コマンドで指定された通りに連結します。各々の作者名の全体が使用されます。しかし参考文献が作者でソートされると (すなわち A+ で始まるソート仕様)、作者のラストネームが代わりに使用され (これは曖昧さを持ち込みません)、また作者の頭文字のシーケンスが全ての作者の代わりに使用されます (これも曖昧さを持ち込みません)。いくつかの参考文献の i番目の作者にラストネームだけを使うのは他に参考文献がある時には曖昧であると考えられます。すなわち参考文献の最初の i-1 人の作者が同じで、 i番目の作者は同じでないが、 i番目の作者のラストネームが同じであるような場合です。いくつかの参考文献の作者のシーケンスの適切な頭文字のサブシーケンスは、適切な頭文字のサブシーケンスとしてのサブシーケンスをもつ作者の別のシーケンスをとる参考文献がある場合には、曖昧であると考えられます。作者の頭文字のサブシーケンスが使われる場合、残りの作者は et-al コマンドで指定された文字列で置き換えられます。このコマンドは頭文字のシーケンスを使うことができる以前に満たされる追加の要求も指定できます。 @ は一時的に作者の正式の表現に評価され、ソートのために同等かどうかを比較する作者は同じ表現となります。
%n
%a
%A
%i
%I 参考文献のシリアル番号は % が続く文字に従ってフォーマットされます。参考文献のシリアル番号はこの参考文献として同じ一時的ラベルをもつ先に現れた参考文献の番号に 1 を加えたものとなります。これらの式は一時的に空の文字列に評価されます。
expr*: この参考文献としての同じ一時的ラベルを持つもう 1 つの参考文献がある場合、空の文字列でなければ expr となります。これは一時的に評価され、空の文字列になります。
expr+n
expr-n expr の最初 (+) または末尾 (-) の n 文字の大文字か小文字か数字です。: troff の ( \('a のような) 特別文字は 1 文字としてカウントされます。アクセント文字列は保持されますが、合計にはカウントされません。
expr.l: expr を小文字に変換したものです。
expr.u: expr を大文字に変換したものです。
expr.c: expr を大文字とそれに続く小文字に変換したものです。
expr.r: expr をラストネームが最初に来るように逆にしたものです。
expr.a: ファーストネームが略称になった expr です。 abbreviate コマンドによって指定されたフィールドはラベルが評価される前に略称にされます。このため、 .a は参考文献の中ではなくラベルの中でのみフィールドを略称にしたい時のみ有用です。
expr.y: expr の年の部分です。
expr.+y: expr の年の前の部分、もしくはそれが年を含んでいなければ expr の全体となります。
expr.-y: expr の年の後の部分、もしくは expr が年を含んでいなければ空の文字列となります。
expr.n: expr のラストネームの部分となります。
expr1~expr2: expr1 となります。ただし、 expr1 の最後の文字が - である場合は expr2 に置き換えられます。
expr1 expr2: expr1 と expr2 の結合です。
expr1|expr2: expr1 が空でなければ expr1 となり、それ以外では expr2 となります。
expr1&expr2: expr1 が空でなければ expr2 となり、それ以外では空の文字列となります。
expr1?expr2:expr3: expr1 が空でなければ expr2 となりそれ以外では expr3 となります。
<expr>: このラベルには 2 つの部分があり、 expr によって分離されています。 2 つの部分からなり、最初の部分が同じである 2 つの連続したラベルは最初のラベルに次のラベルの 2 番目の部分を追加し、 separate-label-second-parts コマンド (初期値ではスペースが続くコンマ) によって指定された文字列によって分離することによってマージされます。その結果のラベルもまた 2 つの部分からなるラベルとなり、最初の部分がマージ前の最初の部分となります。さらに追加されるラベルはこれにマージされます。最初の部分が空であっても差し支えありません。これは short-label コマンドで使う式で使うことができます。
(expr): expr と同様です。グルーピングを行なうために使われます。

上述の式は順位 (高いものが最初) の順にリストされます。 & と | は同じ優先順位となります。

マクロインタフェース

各参考文献はマクロ ]- の呼び出しで始まります。文字列 [F は no-label-in-reference コマンドが与えられていないと、この参考文献のラベルになるように定義されます。その後一連の文字列の定義が続きます。定義は各フィールドに 1 つずつで、文字列 [X はフィールド X に対応します。数値レジスタ [P はフィールド P がページの範囲を含んでいれば 1 にセットされます。 [T と [A と [O の数値レジスタは、 .?! の文字のいずれかで終るフィールド T と A と O に対応して 1 にセットされます。数値レジスタ [E は文字列 [E が複数の名前を含んでいれば 1 にセットされます。参考文献にはマクロ ][ への呼び出しが続きます。このマクロの最初の引数には参考文献のタイプを表す数を与えます。もし参考文献がフィールド J を含んでいると、タイプ 1 として分類されます。またフィールド B を含んでいるとタイプ 3、フィールド G か R を含んでいるとタイプ 4、フィールド I を含んでいるとタイプ 2となり、これら以外ではタイプ 0 となります。 2 番目の引数はタイプ other, journal-article, book, article-in-book もしくは tech-report のシンボル名です。 bibliography コマンドによって累積もしくは生成される参考文献のグループは ]< マクロの呼び出しに先行し、 ]> マクロの呼び出しが続きます。

バグ

ラベル表記法において <> 表記は .char 表記の中では無視されます。

Linux マニュアル一覧

[man1] [man2] [man3] [man4] [man5] [man6] [man7] [man8]
[a] [b] [c] [d] [e] [f] [g] [h] [i] [j] [k] [l] [m] [n] [o] [p] [q] [r] [s] [t] [u] [v] [w] [x] [y] [z]