日本語版 Linuxdoc-SGML ガイド さとけん＠ＦｏｒＵｓ,ken@gamba.forus.or.jp 小野＠京大環境地球,ono@jf.gee.kyoto-u.ac.jp (v1.4から) 著 v1.5.1, 18 March 1996 この文書は、SGML 形式で書かれたソースファイルからプレーンテキストや DVI、HTML など様々な形式の文書ファイルへの整形を行なう日本語版 Linux- doc-SGML 文書処理システムを利用するためのガイドです。原版の Linuxdoc- SGML に付属するガイドをもとに、日本語版 Linuxdoc-SGML v1.5 に対応する よう書き下ろしたものです。 ______________________________________________________________________ Table of Contents: 1. 概要 1.1. このガイドについて 1.2. SGML との関係 1.3. jLinuxdoc-SGML の仕組み 1.4. jLinuxdoc-SGML v1.5 の入手とインストール 2. SGML 文書を変換する 2.1. 文書の変換 2.1.1. ポストスクリプトファイルの作成 2.1.2. DVI ファイルの作成 2.1.3. プレーンテキストファイルの作成 2.1.4. HTML ファイルの作成 2.1.5. man ページの作成 2.1.6. GNU info ファイルへの変換 2.1.7. LyX 形式ファイルへの変換 2.1.8. RTF 形式ファイルへの変換 2.1.9. SGML 構文チェックを行うには 2.2. ISO 8859-1 文字セットの扱い 3. SGML で文書を書くには 3.1. 文書の始め方 3.1.1. SGML ファイルの最初 3.1.2. 使用する文字 3.1.3. 特殊文字 3.2. タグ 3.3. 原稿の書き方 3.4. タイトル 3.5. 文章構成 3.6. 文の整形と改行 3.7. コメント 3.8. 打ち込んだ通りに出力する 3.9. プログラムやアルゴリズム 3.9.1. コード環境 3.9.2. スクリーン環境 3.9.3. クオート環境 3.10. フォント 3.11. 箇条書き 3.11.1. itemize リスト 3.11.2. enum リスト 3.11.3. descrip リスト 3.12. 相互参照 3.13. HTML での URL を記述するには 3.14. 目次 3.15. 横線を引くには 3.16. FAQ を記述するには 4. Man ページの書き方 4.1. 全体の構成 4.2. スタイル 4.3. 各章 5. Emacs を使った SGML ファイルの編集 5.1. Mule Version.2 での特徴 5.2. 使う前の準備 5.2.1. 初期化ファイル 5.3. タグの挿入 5.4. フォント変更タグの挿入 5.5. 特殊キャラクタの挿入 5.6. その他の機能 6. 他の版との違い 6.1. 原版 Linuxdoc-SGML v1.5 との違い 6.2. jLinuxdoc-SGML v1.1 との違い 6.3. jLinuxdoc-SGML v1.4 との違い 7. 謝辞 ______________________________________________________________________ 1. 概要 これは Linux 文書用の日本語版 Linuxdoc-SGML 文書処理システム (以 降、jLinuxdoc-SGML) のガイドです。本文書では、SGML 形式のファイルから 他の形式の文書ファイルへの変換方法や、SGML 形式の文書を書く方法につい て記述しています。 原版の Linuxdoc-SGML は Tom Gordon 作の QWERTZ DTD (文書型定義 : Document Type Definition)をベースに、Linux の文書整備を目的として SGML 形式の文書を groff, LaTeX, HTML, GNU info, LyX, RTF 形式へ変換出来るよ うに、DTD と変換定義ファイル(replacement files: 以降 rep と呼びます)を 書き換えたものです。 jLinuxdoc-SGML はそのうち groff, LaTeX, HTML 形式について日本語に対応 し機能拡張したもので、オリジナルのスーパーセットとなっています。 jLinuxdoc-SGML は一般的な文書処理システムとして作られているわけではあ りませんが、HOWTOs、FAQs や (最近の) Linux 文書プロジェクト (LDP: Linux Documentation Project) のマニュアル作成等に使えるように作られて いますので、様々なタイプの文書で利用することができます。ただし、Linux の文書作成に焦点を絞って開発されているので、一般的な文書作成に十分な機 能を持っているわけではありません。例えば画像や数式や表や特殊文字を扱う ことはできません。より一般的な文書に利用したい場合は QWERTZ DTD などと 組み合わせて利用することをお奨めします。 多数のフォーマットの文書を簡単に生成するのが、このシステムの１つの目標 です。今まで、ほとんどの Linux 文書は編集の始めから終りまでプレーンテ キストで作業していました。roff のようにプレーンテキストの整形処理がで きるシステムもありましたが、(WWW : World Wide Web で使うための) HTML、(優秀な文書印刷のための) LaTeX や、texinfo を生成してくれるもの はありませんでした。それゆえ、あなたがこのシステムに無い機能で欲しいも のがあって、たくさんハックする必要が無くて多数のフォーマットで見栄えの 良い文書が生成できるアイデアがあれば私に知らせて下さい！。 利用者の皆様の御意見で、このシステムをよりよくしていきましょう。 この文書は jLinuxdoc.SGML を使って書かれていますので、あなたがこの DTD を使って SGML の文書を書くのに必要な事柄が含まれています。また、HOWTO の例として JE-HOWTO.sgml が、man ページの例としてkon.sgml が、FAQ の例 として FAQj.sgml が linuxdoc-sgml-1.5/doc ディレクトリにありますので、 記述の参考にして下さい。 1.1. このガイドについて このガイドは jLinuxdoc-SGML を用いて SGML 形式で書かれた文書ファイルを 様々な形式のファイルに変換する方法と、jLinuxdoc-SGML 用に定義された SGML のタグの書き方について例を含めて説明しています。インストールと設 定に関しては、README.v1.5j をご覧ください。 Linuxdoc-SGML の最初のガイドは原版の作者であり LDP のまとめ役である Matt Welsh 自身の手によって書かれました。その後 Linuxdoc-SGML が他の人 の手で更新されるようになり、v1.4 から Greg Hankins が大幅に更新してか らはガイドも Greg Hankins によって書き直されました。 一方、日本語版は v1.1 対応版をさとけん＠ＦｏｒＵｓさんが作成し、そのガ イドもさとけんさんが Matt Welsh のガイドをもとに書き下ろしました。現在 のものは、原版 v1.5 のガイドと日本語版 v1.1 のガイドをもとに、小野＠京 大環境地球が新たに書き下ろしたものです。 1.2. SGML との関係 jLinuxdoc-SGML を使用するに当たって、SGML についての詳細な知識は必要で はありません。ただし、SGML がどのような形式のものであり、DTD がどうい うものであるかという程度の知識は持っていた方が理解が速いでしょう。 SGML に関する簡単な解説としては、付属の日本語版 sgmls のガイド sgmls11j.add/sgmlexp.jpn をご覧になるのがいいでしょう。 Matt Welsh が HOWTOs の公式文書形式として SGML を選択し、Linuxdoc-SGML を作成したのは、HOWTOs をネットニュースや書籍や WWW といった多くの媒体 で配布・公開するために、様々な形式の文書ファイルを一元的に作成する必要 ができたためです。 SGML を用いることにより、ひとつのファイルから様々な形式のファイルを高 い品質で作成することが可能となります。別の選択肢として HTML や TeX な どを基にし、それぞれのフォーマッタで様々な形式のファイルへ変換する方法 が考えられますが、これでは基となる形式の性質に特化しているため変換後の ファイルには十分な品質と高い柔軟性が得られません。SGML の特徴である自 由な文書構造の定義によってのみ、高い品質の文書が得られるのです。 Linux JF プロジェクトにおいて、Linuxdoc-SGML の日本語版が作成されたの も同じ理由からですが、もうひとつの理由があります。JF では FAQ を SGML 形式のタグで括ることで抽出するという試みを行なっています。情報抽出とデ ータベース化に SGML を利用し、その文書作成に Linuxdoc-SGML を活用しよ うというわけです。 また、将来文書が全て SGML で統一されれば特定のタグの抽出による文書管理 も可能となります。 1.3. jLinuxdoc-SGML の仕組み jLinuxdoc-SGML は SGML の構文を定義する DTD と、その構文を解釈し構文エ ラーをチェックし各種形式への変換を行なう パーサ と、変換されたファイル を整形するためのツールから成ります。DTD は QWERTZ DTD を基に作られてお り、SGML パーサには土屋 哲さん作の日本語版 sgmls を用いています。整 形・変換用のツールとしては、LaTeX, groff, dvi2ps などが必要となりま す。例として DVI と Postscript への変換の処理の流れを以下に示します。 1. SGML形式 −(構文解釈: sgmls が DTD を解釈)→ 中間形式 2. 中間形式 −(変換: sgmlsasp が LaTeX 用 rep を基に変換)→ LaTeXソース 3. LaTeXソース −(整形: jlatex, dvi2ps などで変換)→ DVI, Postscript sgmls は正確には、構文解釈を行なう sgmls と各種形式への変換を行なう sgmlsasp によって構成されています。 DTD は構文を定義するのに使います。例えば、article の定義は のように記述されます。article は titlepag, header, toc,... といった要 素から成り、それぞれの要素が必要かどうかといった定義がなされます。それ ぞれの要素は、SGML の文書内ではタグとして使われています。この例で は、
, , といったタグが使われることになります。 DTD は sgmls によって解釈されて、ESIS形式 と呼ばれる中間ファイルが作ら れます。 各種形式に対応する rep(変換定義ファイル)を形式ごとに用意することで、様 々な形式に変換することができます。例えば番号なしの箇条書の LaTeX 用の rep は以下のようになります。 + "\\begin{itemize}" + + "\\end{itemize}" + 同じことを HTML 用に定義すると以下のようになります。 + "
    " + + "
" + が LaTeX では\begin{itemize} と変換され、HTML では
    と変 換されます。 新たな形式のファイルへ変換したい場合は、DTD を定義し直す必要はなく、そ の形式に合わせた rep を作ればよいのです。 いったん sgmlsasp で各種形式のソースファイルを作ってしまえば、後はそれ に合わせたフォーマッタで変換を行ないます。LaTeX では、jlatex を用いて DVI ファイルを作り、必要なら dvi2ps などで Postscript ファイルに変換し ます。プレーンテキストなら groff を使います。実際には、フォーマッタだ けでなくいくつかのフィルタを使って整形や調整を行なっているものもありま す。 1.4. jLinuxdoc-SGML v1.5 の入手とインストール jLinuxdoc-SGML v1.5 は、JF の中に含まれます。以下の ftp site の他、国 内の多くの JF の mirror site から入手できます。 JF の里＠京都大学 インストールには、英語版の linuxdoc-sgml-1.5.tar.gz と日本語対応のため のパッチ jlinuxdoc-sgml-1.5.0.diff.tgz の他、groff や perl、 flex、LaTeXなどが必要です。インストールは README.v1.5j を参照して行 なってください。 jlinuxdoc-sgml に関する最新情報は Linux JFの部屋 「linuxdoc-sgml のページ」 にて公開しています。 お気付きの点がありましたら、ono@jf.gee.kyoto-u.ac.jp 宛にメールでご連 絡ください。 2. SGML 文書を変換する 変換するファイル形式によって利用するコマンドやコマンドに与える引数が異 なります。 2.1. 文書の変換 本章では、HOWTO や faq を含む文書の変換方法を説明します。 2.1.1. ポストスクリプトファイルの作成 ポストスクリプト(PS)ファイルへの変換を行うには、sgml2latex を使いま す。 日本語の SGML ファイルを PS ファイルに変換する。 sgml2latex -p ファイル名.sgml 英語の SGML ファイルを PS ファイルに変換する。 sgml2latex -a -p ファイル名.sgml 以上により ファイル名.ps が作成されます。作成されたファイル名.ps は ghostview 等ポストスクリプトファイルのビューワーで見る事ができます。 なお、-a オプションは原版 Linuxdoc-SGML では A4 サイズの用紙の指定と なっていますが、日本語版では用紙サイズは A4 がデフォルトなので、かわり に -u オプションで US letter を指定できるようになっており、 -a はASCII 文字の使用を指定することになります。なお、日本語の文書を変換する場合は 必ず A4 (デフォルト) で使用してください。 2.1.2. DVI ファイルの作成 DVI ファイルへの変換を行うには、sgml2latex を使います。 日本語の SGML ファイルを DVI ファイルに変換する。 sgml2latex -d ファイル名.sgml 英語の SGML ファイルを DVI ファイルに変換する。 sgml2latex -a -d ファイル名.sgml 日本語の SGML ファイルを LaTeX のソースファイルに変換する。 sgml2latex ファイル名.sgml -d オプションを付けると ファイル名.dvi が作成され、オプションを付けな いと ファイル名.tex が作成されます。作成された ファイル名.dvi は xdvi 等の dvi ファイルのビューワで見る事ができます。 2.1.3. プレーンテキストファイルの作成 プレーンテキストファイルへの変換を行うには、sgml2txt を使います。 日本語の SGML ファイルをプレーンテキストファイルに変換する。 sgml2txt -f ファイル名.sgml 英語の SGML ファイルをプレーンテキストファイルに変換する。 sgml2txt -f -a ファイル名.sgml -f オプションを付けないと、more や less で見たときにはボールド体で強調 された文字が表示される状態になります。これはこれで見やすいのです が、muleやviなどで見るとみにくくなります。 roff で出力された強調文字を なくすには、-fオプションを付けて実行します。 以上により、ファイル名.txt が作成されます。 2.1.4. HTML ファイルの作成 HTML ファイルへの変換を行うには、sgml2html を使います。 日本語の SGML ファイルを HTML ファイルに変換する sgml2html ファイル名.sgml 英語の SGML ファイルを HTML ファイルに変換する sgml2html -a ファイル名.sgml HTML ファイルは章ごとにひとつずつ ファイル名-章番号.html という名前で 作られ、さらにインデックス用に ファイル名.html というファイルが作られ ます。これらのファイルは Netscape や Mosaic 等の WWW ブラウザを使って 見ることができます。 2.1.5. man ページの作成 man ページの変換を行うには sgml2txt を使います。 roff 形式のファイルを作る sgml2txt -man ファイル名.sgml cat 形式のファイルを作る sgml2txt -cat ファイル名.sgml いずれの場合も、ファイル名.man というファイルが作られます。 roff 形式 のファイルは、従来の man ページに使われている形式で groff -man -Tnippon ファイル名.man | less とすることで、man コマンドを使って見る場合と同じように読むことができま す。このように roff を通した結果を cat 形式 と言います。 roff 形式の man ページファイルは、ファイル名.章番号 という名前にして /usr/man/ja_JP.ujis/man章番号 というディレクトリにコピーします(linuxの 場合)。cat 形式の man ページファイルは、同じくファイル名.章番号 という 名前にして /usr/man/ja_JP.ujis/cat章番号というディレクトリにコピーしま す。 2.1.6. GNU info ファイルへの変換 GNU info 形式のファイルへの変換を行うには、sgml2info を使います。残念 ながらまだ日本語には対応していません。makeinfo の日本語版に関する情報 がありましたらご連絡ください。 sgml2info ファイル名.sgml とすると、ファイル名.info というファイルが作成されます。 GNU info 形式 のファイルは、emacs の info モードや info コマンドを使って見ることがで きます。 2.1.7. LyX 形式ファイルへの変換 LyX とは LaTeX のインターフェイスとなって WYSIWYG を実現する一種のワー プロです。残念ながら LyX の日本語版はありません。 LyX 形式のファイルへ の変換を行なうには、sgml2lyx を使います。 2.1.8. RTF 形式ファイルへの変換 筆者の不勉強のため、これが何者なのか全くわかっていません。 RTF につい ての情報がありましたらご連絡ください。 RTF 形式ファイルへの変換 は、sgml2rtf を使って行ないます。 2.1.9. SGML 構文チェックを行うには SGML の構文チェックを行うには、sgmlcheck を使います。 sgmlcheck ファイル名.sgml ここでは、DTD に即した構文になっているかをチェックしているだけなので、 正しい変換が行なわれているかどうかは出力結果を見て自分でチェックする必 要があります。 2.2. ISO 8859-1 文字セットの扱い 原版の Linuxdoc-SGML では ISO 8859-1 (latin1) 文字セット についても、 プレーンテキストと LaTeX、HTML、LyX、RTF で利用可能となっています。日 本語版でも利用可能なはずですが試していません。もし問題があったとして も、若干の修正で利用できるはずです。 ISO 8859-1 文字セットを利用するには、-l オプションを付けて、各種のコマ ンドを実行します。 3. SGML で文書を書くには ここでは linuxdoc.dtd を使った文書の書き方について説明します。 3.1. 文書の始め方 一番最初に覚えなければならないことを簡単に書きます。 3.1.1. SGML ファイルの最初 SGML では (コメントは別にして) 必ず で始めなければなりません。この命令は簡単にいうと、``linuxdoc.dtd'' を 使った文書である事を指定しています。 3.1.2. 使用する文字 入力に使用できるキャラクタとしては、かな、漢字、英数字、および次の記号 です。 : ; . , ? ! ` ' ( ) - / * @ ^ _ + = { } | 【注意】 jlinuxdoc-sgml では、EUC 漢字コードを使うようになっていますの で、EUC コードで文書を書くようにして下さい。また、半角カナと呼ばれてい る文字は使えません。 【注意】行頭を . で始めますと、テキストに変換する際に、問題が発生しま す。よって、行頭には . を記述しないようにして下さい。 3.1.3. 特殊文字 SGML では、以下の記号をコマンドとして認識してしまいますので、その記号 を文字として使いたい場合には下のように入力して下さい。 o 左角かっこ ([) を使うには [ と入力します o 右角かっこ (]) を使うには ] と入力します o アンパサンド (&) を使うには & と入力します o 左ブラケット (<) を使うには < と入力します o 右ブラケット (>) を使うには > と入力します o 左ブラケット＋スラッシュ ( であり、終了タグは です。また、開始 タグしか必要としないものもありますし、<タグ名/内容/ という短縮形式もあ ります。 開始タグと終了タグではさまれている部分に、そのタグの内容が適用されま す。 LaTeX の環境と同じようなものですね。 3.3. 原稿の書き方 ドキュメントつまり原稿は、いづれかのスタイルを指定しなければなりませ ん。スタイルには以下のものが指定できます。ほとんど、LaTeX で使われてい るものと同様です。 article もっともポピュラーなスタイルです。HOWTO にはこれを使います。 report レポート形式です。 book 本の形式です。 manpage man ページの形式です。 例えば article を使う場合には、
    本文
    と指定します。 なお、man ページについては、後で詳しく説明します。 3.4. タイトル 文書のタイトル、著者、日付や概要は、スタイル (例えば
    ) の後に 記述します。 文書のタイトルを記述します。(必須) <auther> 著者を記述します。(必須) <trans> 翻訳者を記述します。(オプション) <date> 文書のバージョンや日付を記述します。(オプション) <tdate> 翻訳された文書のバージョンや日付を記述します。(オプション) <abstract>...</abstract> 概要を記述します。(オプション) 例えば、以下のようになります。 <title>SGML を書こう！！ <author>さとけん＠ＦｏｒＵｓ,<tt/ken@gamba.forus.or.jp/ <date>v0.1 alpha, 20 September 1994 <abstract> SGML を使って文書を書いてみよう。 </abstract> 【注意】 <date> は、<author> もしくは <trans> の直後でないと、エラーと なります。 3.5. 文章構成 文章の構成で、章や節を表すものとして、次のようなセクションタグが用意さ れています。これらは、タイトルの後に記述することができます。 <sect> トップレベルの章で、LaTeX の section に相当します。 (1, 2, ...) <sect1> 第 2 レベルの章で、LaTeX の subsection に相当します。 (1.1, 1.2, ...) <sect2> 第 3 レベルの章で、LaTeX の subsubsection に相当します。(1.1.1, 1.1.2, ...) <sect3> 第 4 レベルの章で、LaTeX の paragraph に相当します。 <sect4> 第 5 レベルの章で、LaTeX の subparagraph に相当します。 また、それぞれのタグの直後に、対応した見出しを記述します。 例えば文書の最初に``概要''という章を記述するには、 <sect>概要 とすればよいですし、あなたが今読んでいるこの章は <sect1>文章構成 と記述されています。 セクションタグの後で、実際の本文を書くには <p> タグを本文の前に記述し て下さい。 例えば、次のようになります。 <sect>概要 <p> この文書は、<tt/jlinuxdoc-sgml/ 文書整形システムの... これは、sgmls パーサーに章見出しと本文の区切りを教えているのです。しか し、段落の区切りを指定する必要があるのは、セクションタグの後だけで、そ の後の段落の区切りは空行で大丈夫です。(こういう段落の区切り方は、 LaTeX でよくやられていることでしょう。) 例えば、次のようになります。 <p> ここは最初の段落です。 ここは次の段落です。 ただ、最初の段落以外で <p> タグを使ってはいけないわけではありません。 最初の段落で必ず指定しなければならないだけです。 3.6. 文の整形と改行 jlinuxdoc-sgml では roff、LaTeX、HTML を使って、文書を整形しますので、 文字列や行を自動的に詰めたり、改行したりします。よって、整形ルールはそ れぞれのフォーマッタに依存します。 また、通常 SGML のソース文書での改行は無視されます。強制的に改行を行な う場合は<newline> を行末に挿入してください。また、空行か <p> を挿入す るとその前の文に改行が入り行間が空きます。 また、空白文字の扱いはフォーマッタによって異なります。プレーンテキスト の場合は空白文字をそのまま空白として出力しますが、DVI や PS, HTML では つめて出力(表示)されます。 変換前： 雨が降る降る 雨が降る <p> 遊びに行きたし<newline> 傘はなし 草履の 鼻緒も 擦り切れた 変換後： 雨が降る降る雨が降る 遊びに行きたし 傘はなし 草履の 鼻緒も擦り切れた タイトルページでは、改行は可能ですが空行を作ることはできません。従って <abstract> タグの中で空行を設けたり <p> を挿入してもエラーになるか無視 されます。 なお、roff の整形はあまり精錬されていないため、他の環境でも空行が無視 されたり、逆に空行が多すぎたりすることがあります。そのため、sgml2txt では 3 行以上の空行を 2 行の空行に縮めています。 3.7. コメント SGML 文書のなかに、フォーマット出力には含めないコメントを書くには、 <!-- コメント --> とします。 3.8. 打ち込んだ通りに出力する LaTeX の verbatim 環境と同じように、打ち込んだ通りに出力させるには、 <verb>...</verb> で囲みます。 例えば、 ここは、<verb> と </verb> でかこまれています。 とするには、 <verb> ここは、<verb> と &etago;verb> でかこまれています。 </verb> と記述します。もちろん、空白もそのまま出力されます。 ただし、<verb>...</verb> の中でも、&,</ の 2 文字は使えませんので、そ れぞれ、 o アンパサンド (&) を使うには &ero; o 左ブラケット＋スラッシュ (</) を使うには &etago; と入力します。 また、LaTeX の verbatim 環境を使う関係で、\end{verbatim} は記述しない で下さい。 3.9. プログラムやアルゴリズム プログラムやアルゴリズムをフォーマットするには、基本的には verb 環境を 用いますが、ちょっとアクセントをつける方法を説明します。 プログラムやアルゴリズムの出力には、 <code>...</code> コード環境 <tscreen>...</tscreen> スクリーン環境 <quote>...</quote> クオート環境 が使えます。 3.9.1. コード環境 <code>...</code> ではさまれた部分をコード環境といいます。コード環境 は、ほとんど verb 環境と同じですが、上下に線が引かれます。 例えば、 ______________________________________________________________________ これは <code>...</code> の例です。 ______________________________________________________________________ とするには、 <code> これは <code>...&etago;code> の例です。 </code> とします。 3.9.2. スクリーン環境 <tscreen>...<tscreen> ではさまれた部分をスクリーン環境といいます。スク リーン環境では、自動的にインデント、タイプライタ書体の指定が行われま す。主に verb 環境といっしょに使われます。 例えば、 これは <tscreen><verb>...</verb></tscreen> の例です。 とするには、 <tscreen><verb> これは <tscreen><verb>...&etago;verb>&etago;tscreen> の例です。 </verb></tscreen> とします。 3.9.3. クオート環境 <quote>...<quote> ではさまれた部分をクオート環境といいます。クオート環 境では、自動的にインデントが行われます。 例えば、 これは <quote>...</quote> の例です。 とするには、 <quote> これは <quote>...&etago;quote> の例です。 </quote> とします。 3.10. フォント jlinuxdoc-sgml では LaTeX と同じようなフォントの指定をサポートしていま す。ただし、プレーンテキストにする場合にはフォントの指定は無視されま す。 em 強調 (例:em) it イタリック (例:it) bf ボールドフェース (例:bf) sf サン・セリフ (例:sf) sl スランテッド (例:sl) tt タイプライタ (例:tt) cparam cparam (例:<cparam>) #LaTeX の \cparam{} に相当します。 フォントを指定する場合には、指定する内容をタグではさみます。例えば、タ イプライタ書体にするには、以下のようにします。 Here is some <tt>typewriter text</tt> to be included in the document. また、内容に``/''が含まれない場合には、以下の短縮形式を使う事もできま す。 Here is some <tt/typewriter text/ to be included in the document. ただし、全ての出力形式 (HTML 等) でサポートされているわけではないの で、 bf、it、tt 以外のフォントはあまり使うべきでは無いでしょ う。bf、it、tt だけでも、文書を書くには十分でしょう。 3.11. 箇条書き jlinuxdoc-sgml ではいくつかの箇条書き (リスト) をサポートしています。 サポートしているのは、以下の 3 種類の箇条書きです。 <itemize>...</itemize> 頭に記号を付けた箇条書きです。 <enum>...</enum> 項目に番号を付けた箇条書きです。 <descrip>...</descrip> 見出しを付けた箇条書きです。 3.11.1. itemize リスト itemize リストでは、それぞれの項目の頭に記号が付けられます。例えば、 jlinuxdoc-sgml には o itemize リスト o enum リスト o descrip リスト があります。 と出力するには、 <tt/jlinuxdoc-sgml/ には <itemize> <item>itemize リスト <item>enum リスト <item>descrip リスト </itemize> があります。 のように、リストの先頭で <itemize> を記述し、それぞれの項目の先頭には <item> を付けて、最後に </itemize> を記述します。 当然、ネスト (入れ子) も可能です。 3.11.2. enum リスト enum リストでは、それぞれの項目に番号が付けられます。例えば、 jlinuxdoc-sgml には 1. itemize リスト 2. enum リスト 3. descrip リスト があります。 と出力するには、 <tt/jlinuxdoc-sgml/ には <enum> <item>itemize リスト <item>enum リスト <item>descrip リスト </enum> があります。 のように、リストの先頭で <enum> を記述し、それぞれの項目の先頭には <item> を付けて、最後に </enum> を記述します。 当然、ネスト (入れ子) も可能です。 3.11.3. descrip リスト descrip リストでは、それぞれの項目に見出しが付けられます。例えば、 jlinuxdoc-sgml でサポートされている箇条書きの種類は itemize 頭に・などの記号を付けた箇条書きです。 enum 項目に番号を付けた箇条書きです。 descrip 見出しを付けた箇条書きです。 の3種類です。 と出力するには、 <tt/jlinuxdoc-sgml/ でサポートされている箇条書きの種類は <descrip> <tag/itemize/頭に・などの記号を付けた箇条書きです。 <tag/enum/項目に番号を付けた箇条書きです。 <tag/descrip/見出しを付けた箇条書きです。 </descrip> の3種類です。 のように、リストの先頭で <descrip> を記述し、最後に </descrip> を記述 します。また、それぞれの項目は <tag/見出し/ 内容 と記述します。なお、 見出しの部分に``/''を含めたい場合には、 <tag>見出し</tag>内容 と記述し て下さい。 ただし、LaTeX を使う場合、見出しの部分には、 \ が入力できませんの で、注意して下さい。 当然、ネスト (入れ子) も可能です。 3.12. 相互参照 <sect?> には自動的に通し番号が付けられますが、これを別の部分から参照す る方法を説明します。 まず、参照される部分へのラベル付けを行います。 <sect1>概要<label id="sec-intro"> これで、ラベルが付けられましたので、他の場所で以下のように参照すること ができるようになります。 概要については、<ref id="sec-intro" name="概要">を参照して下さい。 この場合、ref タグによって、sec-intro のセクション番号に置き換えられま す。 また、name は HTML や nroff に変換する場合に必要です。 なお、HTML に変換した場合には、名前の部分をクリックすることによって、 その場所に移動できます。 例えば、この章は``相互参照''です。 【裏技】 せっかくの相互参照も、節や章しか参照できないのではちょっと機能不 足ですね。実は、label は任意の場所に設定することができるのです が、LaTeX での参照の際に節番号を参照するので、節や章しか参照でき ないようになっているのです。だからといってあきらめる必要はありま せん。<htmlurl> というタグを使って解決することができます。 次の節の htmlurlのタグ を参照のこと。 3.13. HTML での URL を記述するには W3 (World Wide Web) で使われる URL (Universal Resource Locators) も記 述することができます。 Mosaic 等で``Linux Documentation Projectのホームページ''と書かれている 部分をクリックすることで、sunsite.unc.edu の /mdw/linux.html ファイル を参照するようにするには以下のようにします。 <url url="http://sunsite.unc.edu/mdw/linux.html" name="Linux Documentation Projectのホームページ"> url の引数には、実際の URL を記述します。また name の引数には URL の名 前や内容を記述しますが、これはオプションですので記述しなくても結構で す。 また、jf.gee.kyoto-u.ac.jp の /pub/JF/misc/linuxdoc-sgml-1.5.tar.gz を ftp して来るようにするには、 <url url= "ftp://jf.gee.kyoto-u.ac.jp/pub/JF/misc/linuxdoc-sgml-1.5.tar.gz"> とします。 例えば、【オリジナルのLinuxdoc-SGML v1.5を入手するにはここをクリッ ク して下さい。】 <ftp://jf.gee.kyoto-u.ac.jp/pub/JF/misc/linuxdoc- sgml-1.5.tar.gz> となります。 さらに、より機能の高い HTML の URL を表記するためには <htmlurl url=.... > というタグを使います。例えば、メールを送るためのアドレスを 書くときには、 <htmlurl url="mailto:ono@jf.gee.kyoto-u.ac.jp" name="ono@jf.gee.kyoto-u.ac.jp"> のように書くことにより、Netscape などの WWW ブラウザ上でメールを送るた めのフォームを出すことができるようになります。 例： ご用命の際は ono@jf.gee.kyoto-u.ac.jp まで。 <htmlurl> タグを使えば以下のようにして、同一文書中のラベルを直接指定す ることもできます。 <htmlurl url="#CrossRef" name="相互参照の節"> を参照のこと。 相互参照の節 を参照のこと。 3.14. 目次 目次を作るのは簡単です。目次をいれたい部分に <toc> を記述するだけです。大抵は、</abstract> の後に記述されるのがよいでしょ う。 ただし、実際に目次が挿入されるのは、LaTeX を通して作られる dvi と PS ファイルのみです。 textファイルでは単に無視されるだけですし、htmlファ イルでは指定しなくても、作成されます。 3.15. 横線を引くには 文書中で ______________________________________________________________________ このように横線を引くには、 <hrule> と記述するだけです。 3.16. FAQ を記述するには ここでは、Linux コミュニティで利用されている FAQフォーマットを記述する 方法を説明します。 たとえば、 [Item] ソフト名やハードウェアや規格・言語などのキーワード [From] 発言者の名前とメールアドレス [Date] 発言した日付 [Q] 質問の詳細 [A] 質問に対する回答 [From] 発言者の名前とメールアドレス [C] 質問あるいは回答に対するコメント(回答に自身がない場合など) と出力したい場合は、 <faq> <keyword>ソフト名やハードウェアや規格・言語などのキーワード <poster>発言者の名前とメールアドレス <pdate>発言した日付 <question> 質問の詳細 </question> <answer> 質問に対する回答 </answer> <poster>発言者の名前とメールアドレス <coment> 質問あるいは回答に対するコメント(回答に自身がない場合など) </coment> </faq> と記述します。 【注意】本来の FAQ フォーマットとの違いは、以下の通りです。 <FAQ> → <faq> <Item> → <keyword> <Subject> → <faq> の前に <sect?> として記述 <Poster> → <poster> <Date> → <pdate> <Q> → <question> </Q> → </question> <A> → <answer> </A> → </answer> <C> → <coment> </C> → </coment> </FAQ> → </faq> FAQ をまとめた、 faqdb 形式のファイルを、jlinuxdoc-sgml で処理できる ファイルに変換するためのフィルタとして、bin/faqdb2doc がありますので、 御利用下さい。このフィルタを使えば、上記の違いも変更されます。 4. Man ページの書き方 この章では jlinuxdoc-sgml を使って、Man ページ を書く方法について説明 します。 4.1. 全体の構成 Man ページは、以下の様に記述します。 <!doctype linuxdoc system> <manpage title="名前"> <sect1>名前 <p> 名前 - 機能の簡単な説明 <sect1>形式 <p> 使用方法 <sect1>機能説明 <p> 詳細な説明 <sect1>オプション <p> コマンドのオプションの説明 <sect1>環境変数 <p> 関連する環境変数の説明 <sect1>ファイル <p> 関連するファイルの説明 <sect1>関連項目 <p> 関連するマニュアルの紹介 <sect1>バグ <p> バグの説明 </manpage> 上記の内、名前(NAME)と形式(SYNOPSIS)と機能説明(DESCRIPTION)は必須です が、それ以外の章は省略可能ですし、他の章を追加することも可能です。例え ば「不具合＆改良案」という章を追加し、コマンドの作者名と連絡先(メール アドレス)を示したりすることはよくあります。 4.2. スタイル スタイルには、<manpage>...</manpage>を指定します。また、<manpage> の部 分で「名前」と「章番号」を指定します。なお、章番号のデフォルトが 1 に 設定されていますので、章番号が 1 の場合には省略できます。 名前が mh-alias、章番号が 5 の場合には以下のようになります。 <manpage title="MH-ALIAS" sectnum="5"> 4.3. 各章 各章は <sect1> を使用して書くことに注意する以外は、他の文書の書き方と 同じです。 man ページのサンプルとして、doc/kon.sgml が添付されています。御参照下 さい。 5. Emacs を使った SGML ファイルの編集 jlinuxdoc-sgml には Emacs で SGML ファイルを編集するための、lnxsgml.el が含まれています。ここでは、このパッケージを使った SGML ファイルの編集 方法について説明します。 なお、lnxsgml.el 以外の Emacs の使い方は説明しませんので、他の解説書を お読み下さい。 lnxsgml.el は SGML ファイル編集用のメジャーモードです。 筆者は、Mule Version.2 を使っていますので、その他の Emacs をお使いの方 で不具合を見付けた方は連絡して下さい。善処します。 5.1. Mule Version.2 での特徴 Mule Version.2 で lnxsgml.el をお使いになりますと、 o メニューバーに``SGML''メニューが登録されますので、キーを覚えなくて もメニュー形式でほとんどの作業ができます。 o (hilit19.el をロードしておくと) SGML のタグ等に色が付きますので、文 との違いが分かりやすくなります。 などの機能があります。 ただし本説明書では、これらの機能については詳しく説明しません。お試し下 さい。 5.2. 使う前の準備 ここでは、lnxsgml.el を使う前にしておかなければならない準備について、 説明します。 5.2.1. 初期化ファイル あなたの .emacs ファイルに以下の行を追加して下さい。 (setq auto-mode-alist (mapcar 'purecopy '(("\\.sgml$" . sgml-mode)))) (autoload 'sgml-mode "lnxsgml" "Major mode fo editing files of SGML." t) これで、.sgml で終るファイルを編集する時は、自動的に lnxsgml.el が読み 込まれるようになります。 5.3. タグの挿入 ここでは、各種タグの挿入に関する機能について、説明します。 C-c a (sgml-abstract) カーソル位置に <abstract> と </abstract> を挿入し、カーソルをタ グの間に移動します。 C-c c (sgml-code) カーソル位置に <code> と </code> を挿入し、カーソルをタグの間に 移動します。 C-c C-r c (sgml-code-region) 指定されたリージョンの最初に <code> を、最後に </code> を挿入し ます。 C-c C (sgml-comment) カーソル位置に <!-- と --> を挿入し、カーソルを開始タグと終了タ グの間に移動します。 C-c C-r C (sgml-comment-region) 指定されたリージョンの最初に <!-- を、最後に --> を挿入します。 C-c C-d (sgml-make-document) 対話的に style name を入力し、以下のタグを挿入します。 <!doctype dtd namesystem> <style name> <title> <author> <date> </style name> C-c d (sgml-descrip) カーソル位置に <descrip> と </descrip> を挿入し、カーソルをタグ の間に移動します。 C-c C-e (sgml-make-environment) 対話的に environment name を入力し、カーソル位置に <environment name> と </environment name> を挿入し、カーソルをタグの間に移動 します。 C-c e (sgml-enum) カーソル位置に <enum> と </enum> を挿入し、カーソルをタグの間に 移動します。 C-c TAB (sgml-item) カーソル位置に <item> タグを挿入し、カーソルをタグの後に移動しま す。 C-c i (sgml-itemize) カーソル位置に <itemize> と </itemize> を挿入し、カーソルをタグ の間に移動します。 C-c l (sgml-label) 対話的に label id を入力し、カーソル位置に <label id="label id"> タグを挿入します。 C-c p (sgml-paragraph) カーソル位置に <p> タグを挿入します。 C-c q (sgml-quote) カーソル位置に <quote> と </quote> を挿入し、カーソルをタグの間 に移動します。 C-c C-r q (sgml-quote-region) 指定されたリージョンの最初に <quote> を、最後に </quote> を挿入 します。 C-c r (sgml-ref) 対話的に ref id と name を入力し、カーソル位置に <ref id="ref id" name="name"> を挿入します。 C-c t (sgml-tscreen) カーソル位置に <tscreen> と </tscreen> を挿入し、カーソルをタグ の間に移動します。 C-c C-r t (sgml-tscreen-region) 指定されたリージョンの最初に <tscreen> を、最後に </tscreen> を 挿入します。 C-c T (sgml-tag) カーソル位置に <tag></tag> タグを挿入し、カーソルをタグの間に移 動します。 C-c C-s (sgml-make-start) 対話的に tag name を入力し、カーソル位置に <tag name> タグを挿入 します。 C-c s (sgml-sect) カーソル位置に <sect> タグを挿入します。なお、``C-u''をいくつ入 力するかによって、セクションレベルが変わります。 C-c s <sect> タグの挿入 C-u C-c s <sect1> タグの挿入 C-u C-u C-c s <sect2> タグの挿入 C-u C-u C-u C-c s <sect3> タグの挿入 C-u C-u C-u C-u C-c s <sect4> タグの挿入 C-c v (sgml-verb) カーソル位置に <verb> と </verb> タグを挿入し、カーソルをタグの 間に移動します。 C-c C-r v (sgml-verb-region) 指定されたリージョンの最初に <verb> を、最後に </verb> を挿入し ます。 5.4. フォント変更タグの挿入 ここでは、フォント変更タグの挿入に関する機能について、説明します。 C-c C-f b (sgml-font-bf) カーソル位置に <bf> と </bf> を挿入し、カーソルをタグの間に移動 します。 C-c C-f c (sgml-font-cparam) カーソル位置に <cparam> と </cparam> を挿入し、カーソルをタグの 間に移動します。 C-c C-f e (sgml-font-em) カーソル位置に <em> と </em> を挿入し、カーソルをタグの間に移動 します。 C-c C-f i (sgml-font-it) カーソル位置に <it> と </it> を挿入し、カーソルをタグの間に移動 します。 C-c C-f f (sgml-font-sf) カーソル位置に <sf> と </sf> を挿入し、カーソルをタグの間に移動 します。 C-c C-f s (sgml-font-sl) カーソル位置に <sl> と </sl> を挿入し、カーソルをタグの間に移動 します。 C-c C-f t (sgml-font-tt) カーソル位置に <tt> と </tt> を挿入し、カーソルをタグの間に移動 します。 C-c C-f C-r b (sgml-font-bf-region) 指定されたリージョンの最初に <bf> を、最後に </bf> を挿入しま す。 C-c C-fC-rc(sgml-font-cparam-region) 指定されたリージョンの最初に <cparam> を、最後に </cparam> を挿 入します。 C-c C-f C-r e (sgml-font-em-region) 指定されたリージョンの最初に <em> を、最後に </em> を挿入しま す。 C-c C-f C-r i (sgml-font-it-region) 指定されたリージョンの最初に <it> を、最後に </it> を挿入しま す。 C-c C-f C-r f (sgml-font-sf-region) 指定されたリージョンの最初に <sf> を、最後に </sf> を挿入しま す。 C-c C-f C-r s (sgml-font-sl-region) 指定されたリージョンの最初に <sl> を、最後に </sl> を挿入しま す。 C-c C-f C-r t (sgml-font-tt-region) 指定されたリージョンの最初に <tt> を、最後に </tt> を挿入しま す。 5.5. 特殊キャラクタの挿入 ここでは、特殊キャラクタの挿入に関する機能について、説明します。 C-c & (sgml-amp) カーソル位置に & を挿入します。 C-c < (sgml-lt) カーソル位置に < を挿入します。 C-c > (sgml-gt) カーソル位置に > を挿入します。 C-c / (sgml-etago) カーソル位置に &etago; を挿入します。 C-c $ (sgml-dollor) カーソル位置に &dollor; を挿入します。 C-c # (sgml-num) カーソル位置に # を挿入します。 C-c % (sgml-percnt) カーソル位置に % を挿入します。 C-c \ (sgml-bsol) カーソル位置に \ を挿入します。 C-c [ (sgml-lsqb) カーソル位置に [ を挿入します。 C-c ] (sgml-rsqb) カーソル位置に ] を挿入します。 C-c " (sgml-dquot) カーソル位置に &dquot; を挿入します。 5.6. その他の機能 ここでは、タグ挿入以外の機能について、説明します。 C-c C-v (sgml-validate) 編集ファイルの SGML 構文チェックを行います。 C-c C-t d (sgml-translate-dvi) 編集ファイルを dvi ファイルに変換します。 C-c C-t p (sgml-translate-dvi) 編集ファイルを PS ファイルに変換します。 C-c C-t h (sgml-translate-dvi) 編集ファイルを HTML ファイルに変換します。 C-c C-t t (sgml-translate-dvi) 編集ファイルを text ファイルに変換します。 > > キーが入力されると、``>''を挿入し、対応する ``<''に一度カーソ ルが移動します。 / / キーが入力されると、``/''を挿入し、対応する``/''に一度カーソル が移動します。 6. 他の版との違い 6.1. 原版 Linuxdoc-SGML v1.5 との違い jLinuxdoc-SGML v1.5 では、原版とほぼ同じ操作でほぼ同じ出力が得られるよ うデザインされており、日本語対応の拡張をした原版のスーパーセットとなっ ています。従ってコマンドの使い方や SGML のタグの書き方はほとんど同じで す。コマンドに関してはデフォルトで日本語対応となっており、"-a" オプ ションを指定することで英語版と同じ動作をします。 英語版にない特徴として、 o 翻訳者や翻訳日に関するタグの追加 o FAQ リストの作成機能とタグの追加 o SGML の文書の作成をサポートする emacs lisp コードの利用 という機能を付け加えています。 なお、GNU info, LyX, RTF 形式への変換の日本語化は行なわれていません。 6.2. jLinuxdoc-SGML v1.1 との違い 原版の Linuxdoc-SGML v1.5 に合わせてコマンド体系が大きく変わり、多くの バグを取り除かれ、出力のデザインが原版に近付きました。コマンドの変更は 以下の通りです。 fmttext → sgml2txt -e プレーンテキストへの変換 fmthtml → sgml2html HTMLファイルへの変換 fmtdvi → sgml2latex -d DVIファイルへの変換 fmtps → sgml2latex -p PSファイルへの変換 fmtman → sgml2txt -man manページファイルへの変換 fmtcheck → sgmlcheck SGMLの構文のチェック SGML のタグの変更はほとんどありませんが、 HTML の高機能な URL に対応し た機能強化がなされています。これに伴い label タグの書き方が変更されて います。``相互参照の'' 節を参照してください。 v1.1 との最大の違いは、v1.5 では原版のスーパーセットとなっていることで す。原版を別途インストールすることなく、英語のファイルの変換も問題なく こなすことができるのは大きなメリットです。 v1.1 からは多くのバグがとれ タグの変更もなされているので、v1.1 のユーザは v1.5 へ移行することを強 くお奨めします。 6.3. jLinuxdoc-SGML v1.4 との違い v1.4 からの変更は原版の更新に合わせたもので、いくつかのコマンド名の変 更とオプションの変更やデザインの変更があります。コマンドの変更は以下の 通りです。 sgml2txt -e → sgml2txt -f 強調なしのプレーンテキストへの変換 sgml2ps -T → sgml2latex LaTeX ソースファイルへの変換 sgml2ps -d → sgml2latex -d DVI ファイルへの変換 sgml2ps → sgml2latex -p PS ファイルへの変換 sgml2* -c → sgmlcheck SGML の構文のチェック オプションの詳細については、それぞれのコマンドのヘルプ(-help を付けて 起動すると表示される)をご覧ください。 デザインの変更には以下のものがあります。 o プレーンテキストでも目次が付くようになった。 o 原版に合わせ、プレーンテキストで1 行以上の余分な空白行があると消去 するよう変更(v1.4 では 2 行だった)。-b オプションで制御可能。 o LaTeX 用の出力のデザインが原版により近くなった。 o 原版に合わせ、HTML の各ページへのリンクの部分が変更された。 また、強調文字をなくしたプレーンテキストの出力ファイル名は v1.4 では .euc という拡張子がつきましたが、v1.5 では原版にあわせて .txt のままと しました。 機能的には、プレーンテキストで目次がつくようになった点以外には大きな変 更はありませんので、v1.4 のユーザが v1.5 に移行する必要性はあまりあり ません。 7. 謝辞 linuxdoc-sgml の日本語化にあたっては、以下の方々に大変お世話になりまし た。 小島＠電中研さん <kojima@komae.denken.or.jp> 土屋 哲さん <tsuchiya@sysrap.cs.fujitsu.co.jp> 箕浦 逸史さん <JBE03235@niftyserve.or.jp> 森本＠IMAGICAさん <morimoto@lab.imagica.co.jp> 片山＠京大理さん <shackon@kaba.or.jp> 山崎＠ＣＲＣ総研さん <c1962@crcsn23.tyk.crc.co.jp> 真鍋＠豊技大さん <manabe@Roy.dsl.tutics.tut.ac.jp> 阿部＠三菱電機さん <hironobu@ap.isl.melco.co.jp> おごちゃん <ogochan@jh4tjw.prug.or.jp> 播口さん <hariguti@lsidiv.kawasaki-steel.co.jp> 進藤秀郎さん <shu@pegasus.rim.or.jp> おざさ＠東北大認知心理情報さん <ozasa@rubin.cpsy.is.tohoku.ac.jp> 抜けている人がいれば、ごめんなさい。