htroff 入門


豊田英司
toyoda@gfd-dennou.org

Abstract

この文書は htroff の典型的使用法を、なるべく簡潔をこころがけて説明します。 読者には WWW と UNIX または MS-DOS (Windows の DOS 窓でもよい) に 親しんでいることと、HTML についての若干の知識が期待されます。 htroff の動作の詳細は「htroff リファレンスマニュアル」( htroff.htm ) で説明されています。


1 htroff とは何か

   htroff は HTML を生成する roff に似たソフトウェアです。

   roff は一群の組版ソフトウェアの名前です。 UNIX には写真植字機のためのファイルを出力する troff と テレタイプのような機械のためにプレーンテキストに近い出力を出す nroff があります。 また、GNU プロジェクトでは groff というものを作っていて、 これはポストスクリプト出力ができたり日本語パッチが出たりしています。

   いまでこそ roff は TeX などとくらべてもあまり流行りませんが UNIX のオンラインマニュアルは roff の man マクロパッケージを使って 書くことになっています。 このマニュアルをうまく HTML に変換したかったのが、 htroff を作ろうと思ったきっかけです。

   作者の悪趣味または不勉強に由来する、 いろいろの非互換性はありますが、 いちおうまあそこそこ roff らしいものはできたと自負しております。 互換性に関する目標は

マクロパッケージを行儀良く使った roff ソースが共有できること
です。

   なお作者不勉強につき元祖 roff のちゃんとしたマニュアルをみたことがありません。 したがって roff の挙動と称するものは利用例・関連文書・実験結果 などからの推測が多分に混じっています。 もし間違いなどありましたらお知らせいただけると幸いです。

2 簡単な使い方

2.1 起動

   htroff は roff の入力から HTML を生成します。 普通はその入力をファイル (たとえば file.in) にしておくでしょうから、 これをコマンドライン引数 (htroff の後に書く文字列) にして起動すれば htroff はそのファイルを読みに行きます。 なお、入力ファイルは複数指定でき、標準入力を指定するにはファイル名のかわりに - を用います。

$ htroff file.in
こうすると生成された HTML が標準出力にでてきます。

   出力をファイルに書き出すためにはリダイレクト(1)するか、 -o オプションを使います。たとえば出力を output.htm に変更するには

$ htroff -ooutput.htm file.in
とします。

   htroff の使い方は基本的にはこれだけなのですが、 後述するマクロパッケージというものを使う場合は -m オプションを使います。たとえば ms マクロパッケージを使うならば

$ htroff -ms -ooutput.htm file.in
man マクロパッケージを使うならば
$ htroff -man -ooutput.htm file.in
とします(2)
footnote:

(1) リダイレクトとはシェルが標準出力をどこかファイルに指定することです。 シェルのマニュアルをみてね。
(2) ms マクロパッケージのための入力ファイル名は filename.ms のように .ms で終わるようにするのが普通。 また man マクロパッケージのための入力ファイル名は man コマンドが使うので、 htroff.1 のようにピリオドと数字で終わる名前をつけて /usr/man などのディレクトリに置く。 そうでない場合は .man で終わるようにするのが普通。

2.2 マクロパッケージに依存しない話

2.2.1 行の追い込み

   ごく普通にプレーンテキストを書いただけのものも、htroff の正当な入力です(3)。 たとえば次のようなテキストファイルを用意します。

In the beginning God created the heaven and the earth.

And the earth was without form, and void;
and darkness was upon the face of the deep.
And the Spirit of God moved upon the face of the waters.
  And God said, Let there be light: and there was light.

これを htroff で処理した結果は

In the beginning God created the heaven and the earth.
<P>
And the earth was without form, and void;
and darkness was upon the face of the deep.
And the Spirit of God moved upon the face of the waters.
<BR>
  And God said, Let there be light: and there was light.

のようになります。これを WWW ブラウザでみると

In the beginning God created the heaven and the earth.

And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters.
And God said, Let there be light: and there was light.

のようにみえるでしょう。

   まず重要なのは、ほとんどの場合入力の行はたがいにつなぎ合わされ (この操作を 行の追い込み fill-in といいいます)、 WWW ブラウザの幅いっぱいになるところで改行されることです。 この規則の例外は

1)
入力の空行は段落の区切りと解釈される。
2)
入力の行頭に空白 (スペースまたはタブ) のある行は改行される。
3)
改行または段落の切り替えが起こるリクエスト (後述) がある。

です。

footnote:

(3) LaTeX のように最初や最後のおまじないは要らない。なんてすばらしいんだろう!

2.2.2 特殊な意味をもつ文字

   入力の改行がかならずしも出力の改行につながらないことは述べましたが、 その他にも少しだけ (幸いなことに TeX ほど多くはない) 入力したとおり出力されない文字があります。

\ (逆斜線、バックスラッシュ)
行末にある場合、そのバックスラッシュは削除され、 その行はあたかも次の行とつながった1行であったかのように扱われます (継続行)。 それ以外の場合、 バックスラッシュの後に続く文字によっていろいろの機能を持ちます (エスケープシーケンス)。 知っておいてもよいと思われるエスケープシーケンスを下表にまとめます:
行頭の . (ピリオド)
行頭の ' (単引用符)
これらのある行は リクエスト と呼ばれ、 ピリオドや単引用符のあとの文字によって いろいろな機能を果たします。 たとえば、行頭に ".br" と書いた場合は .br リクエストと呼ばれ、その位置での改行を指示するものです。
エスケープシーケンス 機能
\& 長さ 0 の文字列 (行頭にピリオドを書くためなどに利用)
\e バックスラッシュ文字自体を印字
\fB 以下の文字を太字にする
\fI 以下の文字を斜体にする
\fP 太字または斜体の指定を取り消し、直前のフォントに戻す
"\ " (バックスラッシュとスペース) 隙間埋めに用いるスペース
表: エスケープシーケンス

   リクエストには htroff 本来の機能である 組み込みリクエスト マクロ があります。 組み込みリクエストは主に物理的スタイルを指定するものがほとんどで、 htroff と troff や groff などの互換性はあまり高くないので 組み込みリクエストはほとんど文書には直接使用しないことを勧めます。 かわりにマクロパッケージ (後述) に含まれるマクロを用いて より論理的なマークアップを心がけてください。

2.2.3 コメント

   roff のコメントはどうやら「\" 以降行末まで」らしいのですが、 多くのドキュメントはなぜか「行頭に .\" を書く」ようにしています。

2.2.4 とりあえず入力したとおり表示するには

   プログラム断片を引用するときなど、 入力したとおりに出力してほしいものです。 まず行の追い込みを止めるには、 .nf リクエストを用います。このあと .fi リクエストが現れるまで行の追い込みが止まります(4)

   バックスラッシュ (エスケープ文字ともいう) を出力させるためには、 \e のように書きます(5)

   行頭にピリオドまたは単引用符があるとリクエストになってしまうのを防ぐには、 \& を行頭に挿入してください(6)

   また、これは htroff だけの問題 (バグ) ですが、 .nf をしない (行の追い込みが行われる) 状態で スペースをいくつかならべてもひとつのスペースと同じ表示になってしまいます。 これを防ぐにはおのおののスペースの前に \ を挿入してください(7)

   少し実例をあげておきましょう。

プログラム言語 C の教科書の最初によく出てくるのは
以下のような例である:
.\" 以下は行の追い込みをされると読みにくくなる
.nf
#include <stdio.h>

int main() {
printf("Hello, World!\en");
return 0; } .fi これは Kernighan and Ritchie の有名な....

以上のような入力は以下のような出力をうみます:
プログラム言語 C の教科書の最初によく出てくるのは 以下のような例である:
#include <stdio.h>

int main() {
printf("Hello, World!\n");
return 0; }

これは Kernighan and Ritchie の有名な....
footnote:

(4) ms マクロパッケージを用いるときは、 .nf, .fi のかわりに .DS, .DE を用いてください
(5) 多くのプログラム言語のように \\ のように記述しても多くの場合同じ結果になるのですが、 リクエストの引数などではうまくいかないことがあるので使用を避けてください。
(6) もっとも、そんなことをする必要があるのは roff に関する文章を書くとき くらいのものですが。
(7) もっとも、行の追い込みをしておきながらスペースの数を保存する必要が あるとは思えないのですが。

2.3 マクロパッケージ

   マクロ と呼ばれる機能を使って、既存のリクエストや任意のテキストを組み合わせた 新しいリクエストを作ることができます。 といっても通常のユーザにとってマクロを自分でつくることはまれで、できあいの マクロパッケージ というものを使う場合が多いでしょう。 元祖 roff や groff などの処理系には少なくとも man, ms, me の 3 つのマクロパッケージが付属しているようですが、 htroff ではそのうち比較的よく使われる (と作者が判断した) man と ms を実装しています。

2.3.1 man マクロパッケージ

   man マクロパッケージは UNIX のオンラインマニュアル (マニュアルページ man page(s) という) が用いているマクロパッケージです。 現在でも UNIX で動作するプログラムを作るときは man マクロパッケージを 使ったマニュアルをつけるのが普通ですから、 おそらく多くのプログラマにとって roff を学ぶとは man マクロパッケージを 学ぶことにほかならないでしょう。

   マニュアルページの (コメントを除いた) 先頭は .TH マクロの呼び出しで始まります。 なお、tbl(1) などのプリプロセッサを用いる場合は第1行をコメントとし '\" t などとしてプリプロセッサを指定します。 .TH マクロの引数

   その後の

2.3.2 ms マクロパッケージ

  

3 参考にした文書・ソフトウェア

   例示した配布元 URL はかならずしもふさわしくないかもしれません。

groff
fin
tbl.exe
Indian Hill Style Manual
htroff の作者らによる邦訳が http://www.gfd-dennou.org/arch/comptech/cstyle/ で公開されている。
sos
DOS/Windows 版は SOS を利用して perl スクリプトを 実行ファイル (htroff.com) にしている。

4 ライセンスに関する問題

   htroff はフリーソフトウェアたることを意図して作成されています。 配布条件は添付の COPYING.TXT ファイルに書かれています。


HTML generated using htroff at 28 August 1999 22:36:29.