書式

rman [ options ] [ file ]

説明

PolyglotMan は UNIX 系 OS のほとんどで使われているマニュアルページ を入力とし、これらを各種テキストのソース形式に変換する。 PolyglotMan は以前は RosettaMan と呼ばれていた。 バイナリの名前は rman のままであるが、これはこのツールを使ってい るスクリプトのためである。 覚えるためには単に "reverse man" と考えておけばよいだろう。 以前の PolyglotMan では処理の前にページを nroff で整形しておく 必要があった。バージョン 3.0 からは、このプログラムは [tn]roff のソースを入力するほうがよく、普通はその方が良い出力を 得られる。 また、ソース処理は表組を変換する唯一の方法である。 しかし、ソース形式を変換した結果は整形済みのテキストを変換したものほど 表現力がないので、整形済みのテキストを予備として変換してみるとよい。

[tn]roff のソースを解析するにあたっては、いくらでも大きな [tn]roff の サブセットを実装できるだろう。 しかし作者はそれを行わなかったし、行うつもりもないので、変換結果が足り ないことがあるかもしれない。 しかし、マニュアルページ使われる重要な部分は実装しており、それには tbl (ただし eqn は実装していない)、if による評価、汎用マクロ定義などが ある。したがって、普通は変換結果はきれいに見える。 きれいに見えない場合は、PolyglotMan にかける前に nroff でページを 処理すること。 ただし、ある種のページ群で使われている重要なマクロを PolyglotMan が識別 できない場合は、筆者にソースと nroff 処理したページを uuencode したも のを送ってもらえれば手伝えることがあるだろう。 .so (ソース指定または取り込み)マクロを使って他の [tn]roff ソースを 取り込んだりリダイレクトしているマニュアルページのソースを PolyglotMan にかける場合は、そのページの親ディレクトリにいなければならない。 というのも、その前提の下にページが書き出されるからである。 例えば /usr/man/man1/ls.1 を変換する場合は、最初に /usr/man に cd する こと。

PolyglotMan は次の OS に付属するマニュアルページを処理できる: SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System V, OSF/1 (別名 Digital UNIX), DEC Ultrix, SGI IRIX, Linux, FreeBSD, SCO。 ソース処理は次の OS のもので動作する: SunOS, Sun Solaris, Hewlett-Packard HP-UX, AT&T System V, OSF/1 (別名 Digital UNIX), DEC Ultrix。 このプログラムは印刷可能な ASCII のみのテキスト(制御文字は削除される) やセクションヘッダのみの出力、Tk, TkMan, [tn]roff (従来のマニュアルページのソース), SGML, HTML, MIME, LaTeX, LaTeX2e, RTF, Perl 5 POD を作成できる。モジュール化されたアーキテクチャを使って いるので、新しい出力形式の追加は容易である。

PolyglotMan の最新版はいつでも ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z から入手できる。

オプション

以下のオプションは他のオプションと組み合わせて使ってはならない。 これらは入力をまったく処理せずに PolyglotMan を終了させる。

-h|--help

コマンド行オプションの一覧を表示して終了する。

-v|--version

バージョン番号を表示して終了する。

たくさんのパラメータが設定されるので、以下のフィルタは最初に指定しなけ ればならない。他のオプションはその後で指定すること。

-f|--filter <ASCII|roff|TkMan|Tk|Sections|HTML|SGML|MIME|LaTeX|LaTeX2e|RTF|POD>

出力フィルタを指定する。 デフォルト値は ASCII である。

-S|--source

PolyglotMan は入力がソース形式か整形済みテキストかを自動的に判別しよう とする。このオプションは入力がソース形式であることを指定する。

-F|--format|--formatted

PolyglotMan は入力がソース形式か整形済みテキストかを自動的に判別しよう とする。このオプションは入力が整形済みテキストであることを指定する。

-l|--title printf-string

HTML モードにおいて、マニュアルページの <TITLE> オプションを設定する。 パラメータは -r と同じ形式で与える。

-r|--reference|--manref printf-string

HTML モードおよび SGML モードにおいて、他のマニュアルページを 取得するための URL を設定する。 この文字列からは指定された 2 つのパラメータを利用できる。 つまりマニュアルページの名前とセクション番号である(後述の実行例を参 照すること)。 文字列が空(シェルで "-r ''" を指定するなど)や `-', `off' である場合、 HREF によるマニュアルページの参照は行われず、単に斜体文字で表示される だけである。 システム側の printf が XPG3 の位置指示子に対応していれば、この オプションはかなり柔軟に利用できる。

-V|--volumes <colon-separated list>

他のマニュアルページとの相互参照を探す時のチェックに使う 正しいボリューム文字のリストを設定する。 デフォルト値は 1:2:3:4:5:6:7:8:9:o:l:n:p である(ボリューム名では 複数個の文字が使える)。 ページ中の空白を含まない文字列の直後に左括弧があり、その後に正しい ボリューム文字の列が続き、最後に右括弧で終わる場合には、 その文字列は他のマニュアルページの参照であると判定される。 -V に指定する文字が等号(=)で始まる場合、 有効なボリューム文字に一致する文字列と右括弧の間には他の文字はあっては ならない。 (このオプションは SCO UNIX のために必要である)。

以下のオプションは、入力として整形済みのページが与えられた場合だけ有効 である。ソースを与えた場合は使われないので、正しく処理されることになる。

-b|--subsections

セクションの題名に加えて、サブセクションの題名を識別しようとする。 一部の UNIX 系 OS では問題を起こすかもしれない。

-K|--nobreak

マニュアルページに改ページが含まれないことを指示する。 したがって、改ページの前後のフッタやヘッダを探さない。 (古めの nroff の -man マクロは必ず改ページを入れるが、最近は ベンダによっては印刷を troff 経由で行い、画面表示を nroff の -man マクロで行うので、改ページが削除されている。) PolyglotMan は普通はこのフラグがなくても正しく動作する。 )

-k|--keep

ページの終わりの表示を揃えるため、ヘッダとフッタをそのままにする。

--changeleft

(Tcl/Tk のマニュアルページでそうなっているように)チェンジバーを左へ寄せる。

--notagressive

マニュアルページの解析を攻撃的に行わないようにする。 攻撃的な解析(デフォルト動作)では、ページ解析によりヘッダやフッタ、 セクション指定などが削除される。

-n|--name name

マニュアルページの名前を設定する(roff 形式で使われる)。 ファイル名が「" name . section "」の形式で指定されている 場合、名前とセクションは自動的に決められる。 ページが [tn]roff のソースから解析されていて、かつ .TH 行がある場合は、 この情報はその行から取り出される。

-p|--paragraph

パラグラフモードをトグルさせる。フィルタは nroff が行うように改行を行 うかどうか、あるいは複数行をまとめてパラグラフにするかどうかを決める。 主に内部的に使われる。

-s|section #

マニュアルページのボリューム(別名セクション)番号を設定する(roff 形式で 使われる)。 --tables テーブルの解析を攻撃的に行う。

-t|--tabstops #

文字数を減らすために空白文字の代わりにタブ文字を使うマクロセットのため に、# カラムおきにタブ停止位置を設定する。 デフォルト値は 8 である。

各種フィルタについての注意

ROFF

一部の UNIX 系 OS には、マニュアルページの [tn]roff ソースが付属してい ない。そのため、レーザープリンタもタイプライタと大差なくなってしまう。 このフィルタは元の [tn]roff のディレクティブを推定しようとする。 これは後で [tn]roff を使って再コンパイルできる。

TkMan

TkMan (ハイパーテキスト型のマニュアルページブラウザ)は、 PolyglotMan を使ってマニュアルページを表示する。 この際に(普通は)各ページの不要なヘッダやフッタは表示しない。 このプログラムはまた、セクションと(オプションで)サブセクション のヘッダを集め、プルダウンメニューから直接アクセスできるようにする。 TkMan と Tcl/Tk (TkMan が使っているツールキット)は ftp://ftp.smli.com/pub/tcl/から anonymous FTP で入手できる。

Tk

このオプションは、テキストを Tcl のリストの並びとして出力させる。 このリストはテキストとタグのペアを持っており、このタグ名はだいたい HTML と同じである。 この出力は Tk のテキストウィジェットに差し込むことができる。 差し込むためには eval <textwidget> insert end <text> を使う。 この形式は、テキストとタグを使う他のプログラムでも比較的容易に解析でき るはずである。 ASCII も参照すること。

ASCII

ラインプリンタに印刷するとき、マニュアルページは文字を重ね打ちすること によって特殊なテキスト効果を出そうとする。 重ね打ちするのは同じ文字(ボールド)やアンダースコア(下線)である。 他のテキスト処理ソフトウェア(テキストエディタ、検索プログラム、 インデックス作成プログラム等)はこれに対応しなければならない。 ASCII フィルタはこの整形処理を取り除く。 nroff の出力をパイプで col -b に渡しても整形処理を取り除くことが できるが、このプログラムは見苦しいページヘッダやフッタも取り除く。 Tk も参照すること。

Sections

セクションと(オプションで)サブセクションの題名を出力する。 これはマニュアルページを処理する他のプログラムと組み合わせると 便利である。

HTML

HTTP サーバに Mosaic や他の WWW ブラウザのための簡単な拡張を加えると、 PolyglotMan は高品質な HTML を動的に生成できる。 こういった拡張や、その他の拡張へのポインタが PolyglotMan の contrib ディレクトリに入っている。

SGML

これは Docbook DTD へのアプローチであるが、誰かこの分野に本当に興味を 持っている人が、生成されるタグを改善してくれることを期待している。 現在、どれだけタグが近いかを確認してみてほしい。

MIME

MIME (Multipurpose Internet Mail Extensions, RFC 1563 で定義されている) は MIME 対応のメーラや Emacs (19.29 以降) の書式付き文書で使うとよい。

LaTeX および LaTeX2e

どうしてないのだろう?

RTF

Mac や NeXT 等で使える出力である。 適当なマニュアルページを拾って、NeXT の文書システムと統合してよりよく できるだろう。 NeXT はたぶん、これを行うための独自のマニュアルページ用マクロを持って いる。

PostScript および FrameMaker

PostScript を生成するには、groff または psroff を使う。 FrameMaker MIF を生成するには、FrameMaker の組み込みフィルタを使う。 どちらの場合も、[tn]roff のソースが必要なので、 整形済みのマニュアルページしかない場合には、PolyglotMan の roff フィルタを先に使うこと。

実行例

整形済み のマニュアルページである ls.1 を [tn]roff ソース の形式に戻すには次のコマンドを実行する:

rman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1

大きなマニュアルページはディスクの節約のために圧縮されていることが多い (圧縮は整形済みのマニュアルページに対しては特に有効である。というのも、 文字と空白が多いからである)。これは長いマニュアルページであり、 たぶんサブセクションを持つ構成なので、分割を試みる(マクロセットによっ ては、サブセクションを区別していないので、PolyglotMan がうまく 検出できない)。 これを LaTeX 形式に変換してみよう:

pcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f latex > automount.man

別の指定方法としては man 1 automount | rman -b -n automount -s 1 -f latex > automount.man がある。

HTML/Mosaic のユーザのために、PolyglotMan はソースコードを修正し なくても他の HTML マニュアルページを指す HTML リンクを生成できる。 HTML マニュアルページは予め生成しておいても動的に作ってもよい。 まず、予め生成しておく HTML マニュアルページは /usr/man/html に置くものとする。 これらをひとつずつ作るには以下のようにする:
rman -f html -r 'http:/usr/man/html/%s.%s.html' /usr/man/cat1/ls.1 > /usr/man/html/ls.1.html

HTML クライアントが拡張してあり HTML を動的に生成できるなら、 HTML を生成する時には以下のようにする:
rman -f html -r 'http:~/bin/man2html?%s:%s' /usr/man/cat1/ls.1

作者

PolyglotMan
Thomas A. Phelps ( [email protected] ) が University of California, Berkeley の Computer Science Division で開発した。

マニュアルページの最終更新日: $Date: 2001/01/13 14:56:25 $