PolyglotMan, rman -
マニュアルページを整形済みの状態から、各種ソース形式に逆コンパイルする
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
はどんな場合でも完璧に動作するわけではないが、
たいていはうまく動作し、どんな場合でもマニュアルページを編集しやすい形
に変換する際の手間を軽減できる。
整形済みのページの表組(特に
HP
のもの)はあまりうまく扱えない。
表組を認識させるにはそのページのソースを渡すようにすること。
マニュアル用のページャである
woman
はマニュアルページの
整形に独自の考え方を適用している。これは
PolyglotMan を混乱させる。
整形済みのマニュアルページのテキストを直接
PolyglotMan に渡すこ
とにより、
woman
を回避すること。
[tn] roff の出力形式では fB
でボールド体への切り替えを行う。
システムの持つマクロセットが
.B
を要求する場合には、
PolyglotMan
の出力に後処理を加える必要がある。
関連項目¶
tkman(1) ,
xman(1) ,
man(1) ,
man(7)
または
man(5)
(これは使っている UNIX
系 OS ごとに異なる)
PolyglotMan
Thomas A. Phelps (
phelps@ACM.org ) が University of California,
Berkeley の Computer Science Division
で開発した。
マニュアルページの最終更新日:
$Date: 2001/01/13 14:56:25 $