名称

groff_www -ウェブページのオーサリング用 groff マクロ

書式

groff -mwww [ options ] file ...

解説

このマニュアルページは、GNU -mwww マクロについて解説しています。これは、groff ドキュメント書式設定システムの一部です。このマニュアルページは、ごく基本的なガイドに過ぎませんし、 html デバイスドライバ ( grohtml) は完全に書き直されましたがいまだにアルファ版という段階です。多くの人達がテストする機会を持てるようにするため、このマクロを配布物に含めているのです。このマクロファイルは、 -Thtml を使用すれば ( troffrc ファイルによって) 自動的に呼ばれるのだということに注意してください。

ハイパーリンクが動作することを確認するには、このマニュアルページを grohtml デバイスを用いて書式設定してください。

このマクロセットで見つかる機能の概要です。
.JOBNAME 出力を複数のファイルに分割する
.HX 自動的なヘッダレベルの切り捨てる
$1 がセクション/ヘッダを指す
.BCL ウェブページの色を指定する
.BGIMG 背景画像を指定する
.URL 2 つのパラメータを用いて URL を作成する
.FTP FTP への参照を作成する
.MTO HTML email アドレスを作成する
.FTP FTP への参照を作成する
.TAG HTML の name を作成する
.IMG 画像ファイルを挿入する
.PIMG PNG 画像を挿入する
.MPIMG PNG を余白に置き、その周辺をテキストで包む
.HnS 見出しを開始する
.HnE 見出しを終了する
.LK 自動的に収集されたリンクを出力する
.HR 水平罫線を出力する
.NHR 罫線の自動生成を抑制する
.HTL HTML タイトルのみを作成する
.HEAD データを <head>ブロックに追加する
.ULS 順序無しリストを開始する
.ULE 順序無しリストを終了する
.OLS 順序付きリストを開始する
.OLE 順序付きリストを終了する
.DLS 定義リストを開始する
.DLE 定義リストを開始終了する
.LI リスト項目を挿入する
.DC ドロップキャピタルを作成する
.HTML HTML の生リクエストをデバイスドライバに渡す
.CDS コードサンプルを開始する
.CDE コードサンプルを終了する

pic, eqn, refer, tbl プリプロセッサの出力は、入力として受け付けることができます。

リクエスト

.JOBNAME filename: 出力を複数の HTML ファイルに分割します。ファイルは、.SH または .NH 1 に出会うたびに分割されます。その引数は、将来の出力ファイルのためのファイルの語幹 (stem) の名前です。このオプションは grohtml の -j オプションと同等です。

.HX n: 見出しに対して自動的に作成されるリンクの切り捨てレベルを決定します。パラメータに 2 を指定すると、 grohtml は .NH 1 と .NH 2 にはリンクのリストを作成しますが、 .NH 3 に対してはしません。

: .HX
0

: とすると、 grohtml がリンクを生成しないようになります。自動的な見出しをオフにする別の方法は、 groff のコマンドラインスイッチ -P-l です。

.BCL foreground background active not-visited visited: 5 つパラメータを取ります: 文字色、背景色、アクティブなハイパーリンクの色、まだ訪問したことがないハイパーリンクの色、そして訪問したことのあるハイパーリンクの色です。

.BGIMG imagefile: このマクロの唯一のパラメータは、背景画像ファイルを示します。

.URL url [description] [after]: 1、2 または 3 つの引数を使用して URL を生成します。第 1 パラメータはリンク名、第 2 パラメータは実際の URL、そして第 3 パラメータは省略可能であり直後に印字されます。 description と after がないなら、 url はアンカーテキストになります。実際の URL を印字中はハイフネーションは無効化されます。明示的な改行位置を \: エスケープで挿入すべきです。以下にをどのようにエンコードすべきかを示します:

: .URL http://\:foo.\:org/ foo :

: これを -Thtml 以外のドライバで処理すると、次のようになります:

: foo <http://foo.org>:

: URL マクロはどんなタイプでも構いません。例えばは次のように参照できます:

: .URL pic.html "Eric Raymond's pic guide"

.MTO address [description] [after]: HTML 用の電子メール参照を生成します。最初の引数は電子メールアドレスとして必須です。第 2 引数はオプションであり、ブラウザに表示されるテキストです。空の引数が与えられるなら、代わりに address が使用されます。オプションの第 3 引数はその直後に印刷 (表示) されるものです。実際の電子メールアドレスを印刷する間のハイフネーションは無効です。例えばは次のように実現されます:

: .MTO joe@user.org "Joe User"

: 実際には、groff では URL はテキストとしての空白を一切使わないものとして扱われることに注意してください。このことは、いくつかの問題の原因となりますのでバグだと考えられるでしょう。これを回避するために、 www.tmac は他に影響を与えない空白に展開される幅 0 の文字を挿入します ( -Thtml 付きで実行された場合のみ)。

.FTP url [description] [after]: データが FTP 経由で取得できることを示します。第 1 引数は、URL で、第 2 引数は、ブラウザに表示されるテキストです。第 3 引数は、先に述べたマクロと同様に、第 2 引数の直後に表示されるテキストとして扱われます。第 2 および第 3 の引数はオプションです。実際の URL を印字する間、ハイフネーションは無効化されます。例として、これは、です。このマクロの例は、次のように指定します:

: .FTP ftp://\:ftp.gnu.org/ "GNU ftp server" .

.TAG name: 引数から HTML の name タグを生成します。このタグは、マクロを使って参照できます。御覧の通り、同一ドキュメント内の参照ですので、タグ名の前には # を付けなくてはなりません。このリンクは、先の URL マクロの記述の中で TAG を置くことで実現したのです。ソースは次のようになります:

: .TP
.B URL
は、
.TAG URL
すなわち 2 個か 3 個の引数を使用する URL を作成します。
...

.IMG [-R|-L|-C] filename [width] [height]: ドキュメントに画像を含めます。第 2 のオプションは、水平位置、すなわち右・左・中央を指定します ( -R, -L, -C)。位置合わせはデフォルトで中央です (-C)。第 2 引数は画像ファイルです。オプションの第 3 引数と第 4 引数は、幅と高さです。幅を指定しないと、デフォルトの 1 インチになります。高さを指定しないと、幅と同じになります。これは、HTML の IMG タグにマップされます。 PNG 画像を挿入する場合、 PIMG マクロを使用することをお勧めします。

.PIMG [-R|-L|-C] filename [width [height]]: PNG フォーマットの画像を含めます。このマクロは IMG マクロとまったく同じパラメータを取ります。 PostScript と HTML デバイスと連携動作するという利点があります。また、 netpbm パッケージの pngtopnm, pnmcrop, pnmtops を使用して、自動的に画像を EPS フォーマットに変換するという利点があります。ドキュメントを -Thtml で処理しない場合、groff の -U オプションが必要です。

.MPIMG [-R|-L] [-G gap] filename [width [height]]: PNG 画像を余白に置き、その周辺をテキストで包み込みます。第 1 パラメータはオプションです。位置合わせ: 左か右 ( -L または -R) は画像が置かれるマージンを指定します。デフォルトの位置合わせは左 ( -L) です。オプションで、 -G gap は、画像と画像を包み込みテキストの間隔 (gap) を調整するために使用することができます。デフォルトの間隔幅は、0 です。

省略できない第 1 引数はファイル名です。オプションのその後の引数は、幅と高さです。幅を指定しないと、デフォルトの 1 インチになります。高さを指定しないと、幅と同じになります。例:

: .MPIMG -L -G 2c foo.png 3c 1.5c

: また、高さと幅はパーセンテージで与えることもできます。 PostScript デバイスは、 .l レジスタから幅を、 .p レジスタから高さを計算します。例えば:

: .MPIMG -L -G 2c foo.png 15%

.HnS n: 見出しを開始します。数値の見出しレベル n は、第 1 パラメータによって指定されます。利用者の見出しに URL、FTP または MTO マクロを含むなら、このマクロを使用してください。例:

: .HnS 1
.HR
GNU Troff
.URL http://groff.ffii.org (Groff)
— a
.URL http://www.gnu.org/ GNU
project.
Hosted by
.URL http://ffii.org/ FFII .
.HR
.HnE

: この場合、利用者は見出しへの自動リンクを無効としたいかもしれません。これはコマンドラインで -P-l によって行うことができます。

.HnE: 見出しを終了します。

.LK: この位置に自動生成リンクを置くよう、grohtml に強制します。マニュアルページを -Thtml で処理した場合、リンクはここに見えます。

.HR: -Thtml のための全幅の水平方向の罫線を生成します。他のすべてのデバイスには影響はありません。

.NHR: grohtml がデフォルトで生成する、トップとボトムの罫線の生成を抑制します。

.HTL: HTML タイトルのみを生成します。 ms マクロパッケージの TL マクロは、HTML タイトルと <H1>見出しの両方を生成します。これを使って、サーチエンジン用の食材として HTML タイトルを提供し、ドキュメント中では画像のタイトルを使用できます。このマクロは、空白行または改行 (.sp、.br) に会うと終了します。

.HEAD: 任意の HTML データを <head>ブロックに追加します。 -Thtml で処理されないなら、無視されます。例:

: .HEAD
"<link \ rel=""icon""\ type=""image/png""\ href=""http://foo.org//bar.png""/>"

.HTML: このマクロより後の全テキストは生の HTML として扱われます。 -Thtml 無しでドキュメントを処理すると、このマクロは無視されます。内部的に、他の高位のマクロの構成要素としてこのマクロが使用されています。

: 例えば BGIMG マクロは次のように定義されています。

: .de BGIMG
. HTML <body background=\$1>
..

.DC l text [color]: ドロップキャピタルを生成します。第 1 パラメータは、ドロップされ拡大される文字であり、第 2 パラメータ text は最初の文字を超えるべきでない高さの ajoining テキストです。オプションの第 3 パラメータはドロップされた文字の色です。デフォルトは黒です。

.CDS: 等幅のフォントでコードセクションの表示を開始します。

.CDE: コードの表示を終了します。

セクション見出しのリンク

デフォルトで、 grohtml は、すべてのセクションの見出しへのリンクを生成して、HTML ドキュメントの先頭にこれらを置きます。 (どのように、これをオフにするか、または位置を変更するかの詳細についてはを参照してください)。

GROHTML の制限

tbl 情報は、現在 PNG 画像として描かれます。

作者

grohtml はによって書かれました。

バグ

バグレポートはへ送ってください。バグが再現できるように、完全で自己完結している例を付けてください。また、どのバージョンの groff を使っているかも伝えてください。

YOS OPENSONAR

名称

書式

解説

リクエスト

セクション見出しのリンク

GROHTML の制限

関連ファイル

関連項目

作者

バグ