htroff(1)
Date: 1999/01/11
Source: TOYODA Eizi
名前
htroff - HTML ドキュメントを作るための roff もどき
書式
htroff
[
-mmacro
] [
-ooutput
] [
-rnumber=value
] [
-dstring=value
] [
-quser_option
] [
-user_option
] [
files...
]
説明
htroff は HTML を生成するための troff に似た
perl(1)
スクリプトです。
htroff は起動されるとまず
標準マクロパッケージ
と -m オプションで指定された
マクロパッケージ
macro
を読み取り、ついで
files
で指定したファイルを読み取ります。
標準マクロパッケージは htroff 本体 (perl スクリプト) に含まれています。
マクロパッケージ
macro
が指定されたとき、htroff はまずファイル
macro.hma
(環境変数 PATH の各ディレクトリについても探索されます)
を探そうと試み、
これが存在しない場合は htroff 本体に組み込まれている同名のマクロパッケージ
を読み取ろうとします。
ファイル名として - (ASCII HYPHEN-MINUS) 1文字だけを与えた場合は
標準入力が読み取られます。
オプション
-
-mmacro
-
マクロパッケージ macro を読み込むよう指示します。
-
-ooutput
-
出力先のファイルを指定します。
最初に .output output と書かれたファイルを読み込むのと等価です。
-
-rnumber=value
-
数値レジスタ number に value を設定します。
1文字の数値レジスタ
n
については
-rnvalue
と書くこともできます。
-
-dstring=value
-
文字列レジスタ string に value を設定します。
1文字の文字列レジスタ s に等号 (=) を含まない文字列を
設定する場合は
-dsvalue
と書くこともできます。
-
-quser_option
-
-
-user_option
-
ユーザ定義オプション
を設定します。
user_option
の最初の文字がオプション文字と解釈され、
その後に続く文字列が オプションの値 として格納されます。
この値は htroff 式の option 演算子で取り出せます。
たとえば -qazzz または -azzz を与えた場合、リクエスト
.dsexpr foo 'a option
は文字列レジスタ foo に zzz を設定します。
行の読み取りと処理
入力は改行文字 (ASCII LF) によって
行
に区切られます。
改行コードと漢字コードによる障害をさけるために若干のゴマカシ的処理をした後、
行末に逆斜線 (\、シフト JIS 環境ではいわゆる半角の円記号) 文字
がある行はその次の行と連結され、一つの行とみなされます
(継続行)。
このようにして作られた各行について以下の処理が行われます。
-
1. 一部のエスケープシーケンスの処理
-
htroff では逆斜線文字を
エスケープ文字
と呼び、その後に続くある形式の文字列
(エスケープシーケンスescape sequence)
は特別な機能 (多くの場合は特別な文字列に置換される) をもっています。
エスケープシーケンスのうち、
コメントやレジスタ置換などは最初に処理されます。
-
2. 条件分岐などの処理
-
マクロ定義や
条件分岐または
.ig
リクエストによる無視すべき領域が認識されます。
無視すべき行やマクロ定義の中の行の処理はここで終了し、
マクロ定義ならば現在の行がマクロ定義に追加されます。
-
3. リクエストの処理
-
行頭にピリオドや単引用符 ("." や "'")
がある行は
リクエスト
呼び出しです。
行頭にピリオドや単引用符があるだけの行は無視されます
(この判定はコメントの除去の後で行われるので、troff でよく用いられる
コメントである行頭の
.\"
を持つ行はここで無視されることになります)。
-
4. フックの処理
-
行が
.hook
リクエストで登録されたパターンにマッチする場合、
登録されたリクエストが呼び出されます。
これは普通の roff との互換性のない、htroff 独自の機能です。
-
5. 出力処理
-
まだ処理されていないエスケープシーケンスを処理したあと、行を出力します。
出力先はデフォルトでは標準出力ですが、
これは
.output
リクエストによって変更できます。
1行を出力したあと通常は改行が出力されます。
多くの場合 HTML では改行が語の境界つまりスペースひとつに相当するので、
複数の入力行を用いれば複数の語に分離してしまうことに注意してください。
これは後述する
unify
数値レジスタの操作または
\c
エスケープシーケンスによって抑止できます。
エスケープシーケンス
エスケープシーケンスがどの段階で処理されるかは、
マクロ定義または文字列レジスタの定義の中に使用する際に重要な意味を持ちます。
行が読み取られた直後に処理されるエスケープシーケンスは、
マクロ定義を読み取った際に処理されてしまいます。
同じエスケープシーケンスの先頭の
\
を
\\
に書き換えると、
マクロ定義時ではなくマクロ引用時に処理されるエスケープシーケンスとなります。
これに対し、
出力直前に処理されるエスケープシーケンスはマクロ定義中でも
その他のテキスト中でも
\
で書き始めれば以下に記述する機能をもち、
\\
で書き始めればエスケープシーケンスとはなりません。
マクロ定義の前に処理されるエスケープシーケンス
-
\\
-
逆斜線文字1文字に置換されます。
行末に
\\
があると継続行の処理が抑止されます。
行末に逆斜線文字を出力し、さらに継続行を使いたい場合は
行末に
\\\
ではなく
\e\
を書いてください。
-
\. または \'
-
ピリオドまたは単引用符1文字に置換されます。
リクエスト呼び出しを起こさずに行頭にピリオドや単引用符を記述したい時に
この記法を用いることができます
(が、お勧めできません。
\&
の説明を参照してください)。
-
\"任意の文字列
-
コメントです。
\"
から行末までが除去されます。
-
\$#
-
マクロ引用時に処理されるとマクロの引数の個数を表わす10進数に置換されます。
マクロ引用時でない場合は
0
となります。
-
\$*
-
マクロ引用時に処理されるとマクロのすべての引数を " "
(スペース) で区切った文字列に置換されます。
マクロ引用時でない場合は空文字列となります。
-
\$+
-
前項の
\$*
と類似していますが、引数の内部のスペースをすべて
\0
に置換してから処理を行うので、スペースを含んだ引数をとる
リクエストの引数としてこれを与えると、
引数の数え間違えの問題が起こりません。
このリクエストは troff とも互換性のない姑息な対応ですから、
よりよい対応が発見されれば廃止されるかもしれません。
-
\$i
-
i
は 1 から 9 までの数字1字です。マクロ引用時に処理されるとマクロの
i
番めの引数に置換されます。マクロ引用時でない場合は空文字列となります。
-
\n[register]
-
register
は "]" 文字を含まない文字列です。
数値レジスタ
(.nr リクエストの説明を参照してください)
register
の数値を10進表記したものに置換されます。
数値がセットされていない場合は
0
となります。
このエスケープシーケンスは groff にはありますが troff にはありません。
-
\n(re または \nr
-
re
は任意の2字、
r
は任意の1字です。これらは
\n[re]
または
\n[r]
の呼び出しと等価で、troff と互換の形式です。
-
\n+[register] または \n+(re または \n+r
-
これらのエスケープシーケンスを置換する前に数値レジスタ
register
の値に
+register
の値が加算され、その値が評価結果となります。
-
\ssize
-
size
は10進数、あるいはその前に "+" または "-" を前置したものです。
これは troff との互換性のためにあるもので、
フォントの大きさをいじるもののようですが、
現バージョンでは単に無視されています。
-
\*[register]
-
register
は "]" 文字を含まない任意の文字列です。
文字列レジスタ
(.ds リクエストの説明を参照してください)
register
の値に置換されます。
文字列がセットされていない場合は空文字列となります。
このエスケープシーケンスは groff にはありますが troff にはありません。
-
\*(re または \*r
-
re
は任意の2字、
r
は任意の1字です。これらは
\*[re]
または
\*[r]
の呼び出しと等価で、troff と互換の形式です。
出力直前に処理されるエスケープシーケンス
-
\ff
-
f
はフォント (HTML 的にいえば物理的スタイル) を表わす1文字で、現在
B, I, U, R, P
が有効です。
\fB,
\fI,
\fU
はそれぞれ <B>, <I>, <U> タグを生成します。
\fU
は troff とは互換性がありません。
troff との互換性のため
\fBfoo\fIbar
は
<B>foo<B><I>bar
というマークアップを生成し、
斜体の太字を得ることはできません。
\fR
は現在の <B>, <I>, <U> のいずれかを閉じます。
これは troff ではローマン体と呼ばれますが、
HTML 的にフォントの指定をしているわけではないので、厳密には
「斜体でも太字でもアンダーライン付きでもない状態」というべきでしょう。
\fP
は最後の
\ff
の効果を取り消します。これは
\fR
と等価ではありません;
たとえば
\fBbold\fIitalic\fPafter
は
<B>bold</B><I>italic</I><B>after
という結果になります。
troff ではひとつひとつの
\fB
または
\fI
について
\fP
によってその効果が及ぶ範囲を明示するのが
良い文書スタイルとされているようです。
-
\c
-
通常入力の1行が適切な処理を経て出力されると、
最後に改行が出力されます。
行末の
\c
はこの改行の出力を1行だけ抑止します。
広い範囲でこの処理を行いたい場合は
unify
数値レジスタを操作してください。
-
\u
-
これは troff との互換性のためにあるもので、
文字の位置を上げるものです。
現バージョンでは単に無視するのも何なので、
<SUP> タグを用いて fake な対応をしています。
\u と同じ数の \d が同じ行になければなりません。
-
\d
-
これは troff との互換性のためにあるもので、
文字の位置を下げるものです。
現バージョンでの処理については \u を参照してください。
-
\&
-
長さ 0 の文字列に置換されます。
\&
は複数回のマクロ展開で除去されないので、
行頭にピリオドを書く方法としては
\.
より
\&.
のほうが優れています。
-
\| (エスケープ-縦線)
-
これは troff との互換性のためにあるもので、
非常に小さなスペースを意味するもののようですが、
現バージョンでは
\&
と等価な実装になっています。
-
"\ " (エスケープの後にスペース)
-
実体参照
に置換されます。
HTML では <PRE> の中以外では複数のスペースはひとつのスペースと
同じ効果しかありませんが、
"\ " を複数ならべれば、その数に比例した間隔をあけることができます。
マクロの引数での使用についてはバグの項を参照してください。
-
\0
-
実体参照
に置換されます。
troff では
\0
は「数字1つぶんのスペース」を意味するもののようですが、
その意義および "\ " との使い分けについては
作者は詳しくありません。
-
\^ または \l (エスケープ-小文字のエル)
-
現バージョンでは長さゼロの文字列に置換されます。
これは troff との互換性のためにあるものですが、
本来の意義については作者は詳しくありません。
-
\-
-
本来 troff にはハイフンとマイナス記号の区別があります。
-
(ASCII HYPHEN-MINUS) はそのままではハイフンを出力し、
\-
はマイナス記号を出力します。
ダッシュのためにはハイフンではなくマイナス記号を用います。
しかし一般に HTML においては ISO 8859/1 以外の文字が使えることが
仮定できないので、
現バージョンではいたしかたなく
\-
も - を出力する実装になっています。
-
\(ch
-
ch
は任意の2文字で、リクエスト
.char
によって登録された文字
ch
に置換されます。
groff とは違い
\[ch]
とは等価でないので注意してください。
-
\[entity]
-
entity
は英数字からなる文字列です。
これは SGML の実体参照
&entity;
に置換されます。
-
\e
-
エスケープ文字
\
1文字に置換されます。
マクロ展開を繰り返すと
\\\\
のように
\
をいくつか書いてもいつかはエスケープシーケンスとなってしまいますが、
\e
は必ず逆斜線文字を出力します。
使用が推奨されないエスケープシーケンス
以下のエスケープシーケンスは苦し紛れに作ったものです。
本ドキュメントにも現れますが、
使用はマクロパッケージに限定することを強く推奨します。
-
\QA
-
アンパーサンド (&) を HTML ファイルに直接出力します。
-
\QL
-
不等号 (<) を HTML ファイルに直接出力します。
-
\QG
-
不等号 (>) を HTML ファイルに直接出力します。
-
\QQ
-
二重引用符 (") を HTML ファイルに直接出力します。
リクエスト
リクエストは行頭にピリオドや単引用符 ("." や "'") がある時に
実行されるもので、文書によっては「コマンド」と呼ばれることもあります。
リクエスト行は行頭の文字を除いたあと
語
に分解されます。
語とは空白でない文字の並びですが、
二重引用符 (") で囲めば空白文字を含むこともできます。
二重引用符で囲まれた範囲の中で二重引用符をひとつ入れるためには
2 つの二重引用符をならべて書きます。
たとえば「foo bar」と書けば「foo」と「bar」の 2 語となりますが、
「"foo bar"" baz"」は「foo bar" baz」という一語になります。
リクエストの最初の語がリクエスト名です。
他の語はリクエストの
引数
(ひきすう、argument) としてリクエストに「渡され」、
一部のリクエストは引数の内容によってその動作を変えます。
リクエストには
エイリアス、
マクロ、
組み込みリクエスト
の 3 種類があります。
まずエイリアスが定義 (.alias 参照) されている場合、
まずリクエスト名がそのエイリアスの値に置換されます。
次にリクエスト名のマクロが定義 (.de 参照) されている場合、
そのマクロが呼び出されます。
そうでない場合、以下の組み込みリクエストの名であれば
その機能が実行されます。
マクロでも組み込みリクエストでもない場合はそのリクエストは存在しない旨の
エラーメッセージが標準エラー出力に表示されます。
組み込みリクエスト
troff のリクエスト名は2文字未満です。
htroff では他の roff との互換性を考慮した
リクエストにアルファベット 2 文字の名前をつけています。
それ以外の htroff に依存したリクエストの使用は
マクロパッケージに限定することを推奨します。
-
.{ expression
-
普通のプログラミング言語では if にあたるものです。
htroff 式
expression
を評価した結果が真ならば以下のブロック
(.} または .}{ が現れるまで) を有効にします。
なお troff で条件分岐に用いられる
.if,
.ie,
.el
リクエストはまだサポートされていません。
-
.}{ [expression]
-
普通のプログラミング言語では else if にあたるものです。
以前に同じレベルのブロックが実行されておらず、
htroff 式
expression
を評価した結果が真ならば以下のブロックを有効にします。
expression
を与えない場合は常に真となります。
これは普通のプログラミング言語では else にあたるものです。
-
.}
-
.{
または
.}{
リクエストによるブロックの終わりを示します。
-
.alias aliasname [requestname]
-
リクエストのエイリアスを登録します。
この後のリクエスト
.aliasname
または
'aliasname
の呼び出しは
.requestname
の呼び出しと等価になります。
requestname
を指定しない場合はエイリアスが削除されます。
-
.am macro_name
-
ピリオドふたつ
..
だけからなる行までをマクロ
macro_name
に追加します。
-
.as string-register string ...
-
文字列レジスタ
string-register
に
string ...
を追加します。各語の間にはスペースひとつが入れられます。
-
.asexpr string-register expession
-
文字列レジスタ
string-register
に htroff 式
expression
を評価した結果を追加します。
-
.bf [lines]
-
以後の入力のうち
lines
行 (省略時は1行) を太字 (<B> タグによる) で出力します。
-
.bp
-
本来の roff では改ページを意味します。
htroff では
.tag HR
と等価です。
-
.br
-
改行を強制します。
.tag BR
と等価です。
-
.ce [lines]
-
以後の
lines
行を <DIV ALIGN=CENTER> タグを用いてセンタリングします。
この区間では行の追い込みは行われません。
引数
lines
を省略すると行数は 1 とみなされます。
-
.char ch string
-
ch
は任意の2文字です。
文字の登録をします。すなわち
\(ch
は
string
に置換されるようになります。
-
.checkopt optchars
-
ユーザ定義オプションが
optchars
のリストに含まれているか確かめます。
未定義のオプションが与えられていると警告を表示します。
-
.de macroname
-
ピリオドふたつ
..
だけからなる行までをマクロ
macroname
に登録します。
登録したマクロを修正するには
.am
削除するには
.rm
を用います。
-
-
マクロの中でマクロの再定義を行うことはできますが、
再定義を終わらせるための行は
\\..
でなければなりません。
-
.ds string-regiser string ...
-
文字列レジスタ
string-register
に
string ...
をセットします。各語の間にはスペースひとつが入れられます。
登録した文字列レジスタに追加を行うには
.as
を用います。
-
.dsexpr string-regiser expression
-
文字列レジスタ
string-register
に htroff 式
expression
を評価した結果をセットします。
-
.exit [expression]
-
htroff 式
expression
を評価した数値 (省略時は 1) を終了コードとして htroff を終了させます。
-
.fi
-
</PRE> タグを出力し、
.nf
リクエストの効果を打ち消します。
その結果として入力行の追い込み (fill in) が行われるようになります。
-
.getline
-
入力ファイルから次の行を読み取り、
これを語に分解してマクロ引数領域に格納します。
つまり、
.getline
リクエストの後では
\$n
は入力ファイルから得られた
n
番めの語に置換されます。
このリクエストはマクロ引数のかわりに「次の行」を用いる
ある種のマクロを実装するために導入されたものですが、
語分解によって二重引用符が消えてしまうので注意してください。
-
.hook pattern [request]
-
正規表現
pattern
に対するフックを設定します。
すなわち、
pattern
にマッチする入力行 (リクエスト行は含みません) を出力するかわりに
.request
リクエストが実行されます。
request
の中で
pattern
にマッチするテキストを出力させようとすると
無限ループが発生するので注意してください。
-
.ig [terminator]
-
.terminator
という形の行が現れるまでの入力行を無視します。
terminator
が指定されない場合、"." となります。すなわち
..
までが無視されます。
.terminator
の行頭のピリオドは単引用符では代用できません。
-
.input file
-
現在の入力ファイルの次の入力ファイルを
file
にします。それ以前に読み取ることが決まっているファイルは
file
の次に読み取られることになります。
.so
リクエストと異なり、現在の入力ファイルの読み取りは中断しません。
-
.it [lines]
-
以後の入力のうち
lines
行 (省略時は1行) をイタリック (<I> タグによる) で出力します。
-
.keep [macroname]
-
[この機能はよりよい代替手段が開発され次第削除される予定です]
以下の入力によって生成される出力は標準出力やファイルではなく、
マクロ
.macroname
に追加されてゆきます。
引数
macroname
を省略した呼び出しによってこの状態は終了し、
以下の出力は元の出力先にかき出されるようになります。
-
.nf
-
<PRE> タグを出力し、これ以後の入力行の追い込み (fill-in,
複数の入力行をひとつにまとめる処理) を行わないようにします。
<PRE> タグの中ではタブ文字 (ASCII TAB) はスペースと同一視されるのではなく
プレーンテキストと同様にタブ位置までの前進という
効果を持つようになります。
-
.nop
-
なにもしません。
ダミーのマクロを作るときに使います。
-
.nr number_register init incr
-
数値レジスタ
number_register
に数値
init
を代入し、
数値レジスタ
+number_register
に数値
incr
を代入します。
incr
は
\n+
で始まるエスケープシーケンスで用いられる増分となります。
たとえば .nr a 120 2 とした直後は
\na
は 120 に置換されますが、
その後
\n+a
を置換しようとするたびに得られる数値は 2 づつ増えてゆきます。
-
.nrexpr number-register expression
-
数値レジスタ
number-register
に htroff 式
expression
を評価した結果をセットします。
古いバージョンの htroff ではこの機能が
.nr
という名前でしたが、troff や groff との互換性を高めるため
仕様が変更されました。
-
.output file
-
出力先を
file
に変更します。
-
.rm macro_name
-
マクロ
macro_name
を除去します。
-
.shift
-
\$n
で呼び出されるマクロのパラメタの番号を1つシフトします。
たとえば
.shift
の前に
\$2
で呼び出されていたものが
\$1
で呼び出されるようになります。
また \$* の先頭要素もなくなります。
-
.so file
-
入力もとを一時的に
file
に切り替えます。
現在のファイルのまだ読み取られていない部分は
file
の読み取りが終了した後に読み取られることになります。
-
.sp [number]
-
number
個の <BR> タグをいれることによって空行をいれます。
number
を指定しない場合は 1 とみなされます。
-
.tag [tagname [property...]]
-
SGML タグ
<tagname>
を挿入します。
tagname
の先頭に
/
(斜線) を用いれば閉じタグになります。
property
が与えられているときはタグに属性値
property
の指定が入ります。
SGML では属性値の文字列には
単引用符 (') または二重引用符 (") をつけることができますが、
二重引用符をただ書くと " に置換されてしまうので
単引用符をつけることをお勧めします。
どうしても二重引用符をつけるには現バージョンの htroff に依存した方法ですが
\QQ
を使います。たとえば
.tag A HREF=\QQurl\QQ
は <A HREF="url"> を生成します。
\QQ
は htroff に依存するので、
マクロパッケージに隠蔽することを強く推奨します。
-
.ul [lines]
-
以後の入力のうち
lines
行 (省略時は1行) にアンダーラインをつけます (<U> タグによる)。
-
.warn string...
-
string
と改行を
perl(1)
の
warn
を用いて標準エラー出力に出力します。
-
.write string...
-
string
を出力します。
エスケープ文字や & < > などの文字の置換を抑止して
直接文字列を出力したい場合に使えます。
特殊な意味を持つリクエスト
htroff によって自動的に呼び出されるリクエストがあります。
初期値 (標準マクロパッケージの読み込み前) では
これらは .nop へのエイリアスになっていますが、
標準マクロパッケージによってエイリアスが再定義されていますので
mstd(7)
を参照してください。
これらのリクエストを文書に直接記述することは避けてください。
-
.cleanup
-
コマンドライン引数リストのすべてのファイルを処理し終えた時に呼び出されます。
-
.opened
-
コマンドライン引数リストのそれぞれのファイルを開いた後で呼び出されます。
数値レジスタ
数値レジスタは数値を格納するためのレジスタで、
.nr
リクエストで設定されます。
引用には
\n
で始まるエスケープシーケンスを用います。
htroff 本体が利用する数値レジスタの名前を以下に挙げます。
これらを勝手に変更すると htroff がうまく「だまされてくれる」かどうかは
レジスタごとに異なります。
特に注記しないレジスタは変更しないことを勧めます。
-
!
-
perl の $! にあたるものです。
.checkopt
または
.output
が成功したとき 0 に、失敗したときに非 0 に設定されます。
-
center
-
.ce
リクエストによって利用されるカウンタで、
センタリングがあと何行有効かを示します。
-
dst
-
perl の localtime 関数の返却値の中の夏時間フラグが設定されます。
夏時間が使われているときは正、夏時間が使われていない時は 0、
夏時間の有無の情報が得られない時は負の値となります。
-
dw
-
htroff 起動時刻 (localtime) の曜日がセットされます。
日曜日は 0 で、土曜日は 6 で表わされています。
-
dy
-
htroff 起動時刻 (localtime) の日がセットされます。
-
fillin
-
.nf
リクエストで 0 に設定され、
.fi
リクエストで 1 に設定されます。
初期値は 1 となっています。
このレジスタが非 0 になっている場合、
入力のタブ文字は に展開されます。
これはいかなる意味でも正確なタブ処理ではありませんが、
タブによる表を曲がりなりにも見られるようにするための苦し紛れの対策です。
-
font
-
.it
や
.bf
など、フォント (HTML 的にいえば物理的スタイル)
を変更するリクエストによって設定され、
現在のフォントがあと何行適用されるかを表わします。
フォントを変更するエスケープシーケンス (\f で始まる)
によっても変更されます。
-
hour
-
htroff 起動時刻 (localtime) の時 (24時制) がセットされます。
-
jperl
-
動作環境が jperl であることが検出されると非 0 に設定されます。
そうでない場合は 0 に設定されます。
-
min
-
htroff 起動時刻 (localtime) の分がセットされます。
-
mo
-
htroff 起動時刻 (localtime) の月がセットされます。
perl の localtime とは違い、1 月は 1 で表わされています。
-
msdos
-
動作環境が MS-DOS であることが検出されると非 0 に設定されます。
そうでない場合は 0 に設定されます。
このレジスタを変更しても、
htroff 本体の環境依存動作が変化するわけではありません。
-
sec
-
htroff 起動時刻 (localtime) の秒がセットされます。
-
unify
-
このレジスタを 0 以外の値にすると htroff は改行を出力しなくなります。
初期値は 0 となっています。
ここでいう改行とは HTML ファイルのなかに直接書かれた改行のことで、
<BR> の出力や .br リクエストとは関係がありません。
-
yday
-
年初から htroff 起動時刻 (localtime) の日までの通日がセットされます。
1月1日は 1 で表わされます。
-
yr
-
htroff 起動時刻 (localtime) の西暦年から 1900 を減じたものがセットされます。
このレジスタは troff との互換性のため用意されていますが、
19\n(yr
という表現は 2000 年以降は問題を起こすことに充分注意してください。
-
year
-
htroff 起動時刻 (localtime) の西暦年がセットされます。
文字列レジスタ
文字列レジスタは文字列を格納するためのレジスタで、
.ds
リクエストで設定、
.as
リクエストで追加されます。
引用には
\*
で始まるエスケープシーケンスを用います。
htroff 本体が利用する文字列レジスタの名前を以下に挙げます。
-
<
-
入力元のファイル名 (正確には perl のファイルハンドル名) がセットされます。
このレジスタを変更しても入力元が変わるわけではありません。
-
>
-
出力先のファイル名 (正確には perl のファイルハンドル名) がセットされます。
このレジスタを変更しても出力先が変わるわけではありません。
-
font
-
現在のフォント名 (HTML 的にいえば物理的スタイル) がセットされます。
その値としては B, I, U, および空文字列が含まれ得ます。
-
hook
-
フックが起動されるときに
その原因となったパターンがセットされます。
これを用いると複数のパターンでひとつのマクロが起動されるようにしたときに
その原因をマクロ内部で判定できます。
-
lastfont
-
\fP
エスケープシーケンスで戻るべきフォント名がセットされます。
-
line
-
フックが起動される原因となった行がセットされます。
-
match
-
フックが起動されるときに、行の中でパターンにマッチした部分がセットされます。
-
post
-
フックが起動されるときに、行の中でパターンにマッチする前の部分がセットされます。
-
pre
-
フックが起動されるときに、行の中でパターンにマッチする後の部分がセットされます。
htroff 式
リクエスト
.},
.}{,
.asexpr,
.dsexpr,
.nrexpr
の引数では
htroff 式
と呼ばれるスタック型言語を用いて
数値・文字列の演算を行うことができます。
演算は perl のスカラーに対する演算なので文字列と数値の型の区別はなく、
必要ならばこれらは自動的に変換されます。
なお、htroff 式は troff や groff の計算機能とはまったく互換性がありません。
htroff 式はリクエストの解析のときに作られる語を並べたものです。
語は左から順に解釈されます。
一部の語は
演算子
と呼ばれ、いろいろなスタックの操作を行います。
演算子の名前は英小文字だけからなります。
それ以外の語は
リテラル
と呼ばれ、スタックにその語を積む操作を行います。
リテラルが単引用符 (') で始まっている場合は先頭の単引用符が
除去されたものをスタックに積みます。
演算子と混同しないように、英小文字だけからなる語の先頭には
すべて単引用符をつけることを推奨します。
すべての語の評価が終了したとき、スタックトップにある値が
htroff 式の値となります。もしスタックが空ならば未定義値が得られます。
以下に演算子のリストを示します。
見出しは演算子の名前を太字で示し、左側に除去されるスタック要素を、
右側に追加されるスタック要素をそれぞれ斜体で挙げます。
スタック要素の例示が n の場合は整数、x, y, z の場合は実数、
r の場合は正規表現、s, t, st の場合は文字列として
解釈されることを表わします。
p の場合は真偽値で、0 と 1 がそれぞれ偽と真にあたります。
置数演算子
置数演算子はスタックからなにも取り出さずに値を積むものです。
特殊なリテラルと考えることもできるでしょう。
-
undef undef
-
未定義値 a を与えます。
-
null null
-
空文字列を与えます。
-
begin n
-
非常に大きな整数を与えます。
これは数値レジスタによる範囲指定を読みやすくするために導入されました。
-
end n
-
0 を与えます。
-
args n
-
現在解釈されているマクロの引数の数を与えます。
-
a dup a a
-
スタックトップにある値をさらにもう一つ与えます。
何かの値に対し複雑な検査をしたいが値を保存したいときに有用です。
単項演算子
単項演算子はスタックから1つの値を取りだし、
なんらかの処理をして1つの値を積むものです。
いいかえれば、スタックトップの値を変化させると考えてもいいでしょう。
-
s alias t
-
リクエスト s に対するフックとして設定されたリクエスト t を求めます。
-
n arg s
-
現在解釈されているマクロの
n
番目の引数
s
を与えます。
-
s basename t
-
ファイルのフルパス s のうちディレクトリ部分を取り除いた部分
t を求めます。
MS-DOS の場合は漢字コードがらみで問題が発生することがあります。
-
x dec y
-
y=x- 1
を計算します。いいかえればスタックトップの要素を 1 減らします。
もちろん実装は -- 演算子を使っています。
-
a defined p
-
値 a が未定義値でない場合 p が真となります。
たとえば 'name string defined は
文字列レジスタの有無を確かめるに用いることができます。
-
s dir p
-
名前 s のディレクトリが存在するかどうか p を求めます。
-
s dirname t
-
ファイルのフルパス s のうちディレクトリ部分 t を求めます。
MS-DOS の場合は漢字コードがらみで問題が発生することがあります。
-
s env t
-
環境変数 s の値 t を求めます。
環境変数が存在しなければ未定義値が得られます。
-
s file p
-
名前 s のファイル (普通のファイル) が存在するかどうか p を求めます。
-
r hook t
-
パターン r に対するフックとして設定されたリクエスト t を求めます。
フックが存在しない場合は未定義値が得られます。
-
x inc y
-
y=x+ 1
を計算します。いいかえればスタックトップの要素を 1 増やします。
もちろん実装は ++ 演算子を使っています。
-
s length n
-
文字列 s の長さ n を計算します。
-
s lowercase t
-
文字列 s を小文字に変換したもの t を求めます。
-
s macro t
-
マクロ s の内容 t を求めます。
複数行からなるマクロならば
改行コードを含んだ文字列値が得られるので注意してください。
マクロが存在しなければ未定義値が得られます。
-
x nega p
-
数値 x が負かどうか p を求めます。perl でいえば
p=x<0
を計算します。
-
a not p
-
値 x を真偽値として評価し、それを反転します。
-
s number t
-
数値レジスタ s の値 t を求めます。
数値レジスタに値の設定がされていなければ未定義値が得られます。
-
s option t
-
ユーザ定義オプション s の値 t を求めます。
オプションが与えられていなければ未定義値が得られます。
-
x posi p
-
数値 x が正かどうか p を求めます。perl でいえば
p=x>0
を計算します。
-
s string t
-
文字列レジスタ s の値 t を求めます。
文字列レジスタに値の設定がされていなければ未定義値が得られます。
-
s uppercase t
-
文字列 s を大文字に変換したもの t を求めます。
二項演算子
二項演算子はスタックから2つの値を取りだし、
なんらかの処理をして1つの値を積むものです。
-
x y add z
-
加算、つまり
z=x+y
を計算します。
-
a b and c
-
値 a と b の and (論理積) をとります。
perl の && を用いているので c が真になる場合は
b の値をとります。
-
s t cat st
-
文字列 s と t を を連結した結果 st を求めます。
-
s t eq p
-
文字列 s と t が等しいかどうか p を求めます。
-
x y equiv p
-
数値 x と y が等しいかどうか p を求めます。
-
s r grep t
-
文字列 s のうち正規表現 r にマッチする部分 t を残します。
-
s r match p
-
文字列 s が正規表現 r にマッチするかどうか p を求めます。
-
a b or c
-
値 a と b の or (論理和) をとります。
perl の && を用いているので c が真になる場合は
a または b の値をとります。
-
x y sub z
-
減算、つまり
z=x-y
を計算します。
-
s r subpat t
-
文字列 s を perl のカッコ () を含む正規表現 r にマッチさせ、
もっとも左にある括弧にマッチする部分 t を求めます。
特殊な演算子
-
a debug a
-
スタックトップを標準エラー出力に印字します。
スタックには変化が起こりません。
-
;
-
スタックには変化が起こりません。
単にプログラムを読みやすくするために用います。
-
a b exch b a
-
スタックトップの下にある値をスタックトップと入れ替えます。
-
a b pop a
-
単にスタックトップの値が捨てられるだけです。
参考: HTML 以外の SGML の生成
標準マクロパッケージを除いた htroff 本体で生成される可能性のある
HTML タグは、<PRE>, <BR>, <HR>, <B>, <I>, <U> です。
これらが含まれる DTD を使うか、
あるいは使えないタグを生成する部分を改造すれば、
HTML 以外の SGML も多くの場合生成可能です。
もちろん、具象構文があまりに違っていればどうしようもありませんが。
参照
perl(1),
intro(1),
man(7),
ms(7),
mstd(7)
バグ
ヌル文字 (ASCII NUL) と抹消文字 (ASCII DEL) は htroff の内部で
特別な意味で使用され、出力の前に削除されてしまうため、
これらの文字を含む入力の結果は保証されません。
jperl については考慮していますが、動作は確認されていません。
作者不勉強のため troff のマニュアルが手元にありません。
したがって troff の仕様と称するものは経験による推測にすぎません。
行末の
\\
が
必ず
継続行処理を抑止するのはバグです。行末の
\\\
は逆斜線1文字と継続行の印と解釈されるべきです。
元祖 troff ではエスケープ (逆斜線文字) の直後のスペースは
マクロの引数の区切りとはなりませんが、
htroff ではマクロの引数の区切りとなってしまいます。
スペースを含む引数は二重引用符で囲んでください。
DATA ファイルハンドルが使えない perl
(たとえば Diomidis Spinellis の DOS 用 perl) では htroff 本体に含まれた
マクロパッケージが使えません。
標準エラー出力に出力したはずが標準出力に出力されてしまう perl
(たとえば ActiveWare Internet Corp. の Win32 用 perl) では
.warn
の結果でさえリダイレクトされてしまいます。
パイプの利用はあきらめて、
-o
オプションを活用しましょう。
入力の文字コードは ASCII、シフト JIS、各種 EUC、ISO 8859/1、
ISO-2022-JP などが想定されています。
ただし正規表現の字数認識は ASCII 以外については正しく行われません。
UTF-8 はシフト JIS と誤認されます。
htroff では二重引用符や逆斜線に相当するバイトが問題を起こさないように、
内部処理は EUC またはそれに同等なもので行われています。
入力がシフト JIS や ISO-2022-JP であると認識されると、
内部では EUC に変換するようになります。
出力は MS-DOS であることが認識されるとシフト JIS に、
それ以外の場合は EUC になります。
なおこの変換は jperl であることが認識されると抑止されます。
この場合は入力には EUC または jperl でサポートされているエンコーディングを
一貫して用いねばなりません。
htroff 本体は .tag リクエストに応じてそのままタグを出力します。
生成される HTML (と称するもの) のタグ構造を
正当に保つのはマクロパッケージ作成者と利用者の責任です。
(つまり、おとなしく使わないと容易に非文法的な HTML を生成します)
htroff 本体に組み込まれているマクロパッケージを複数指定するには、
htroff 本体に並んでいる順にコマンドラインに指定する必要があります。
この制限は perl の DATA ファイルハンドルのファイル位置を
操作できないことに由来しています。
この結果、たとえば実在しないマクロパッケージと
htroff 本体にあるマクロパッケージを指定すると、
実在しないほうの探索で DATA ファイルハンドルを最後まで読み切ってしまい、
実在するマクロパッケージも見つからないというメッセージを表示します。
このマニュアルは長すぎます。構成を誤りました。
HTML generated using
htroff
at 28 August 1999 22:36:31.