http://jf.linux.or.jp/)
以前から JF で配布され、多くの人々 (私もその一人です) に利用されてきた 「日本語版 Linuxdoc-SGML ガイド」(著者はさとけんさんと小野さん) は LDP で開発された linuxdoc-sgml を日本語に対応させ、また DTD に FAQ 関連など いくつかの拡張を加えた jLinuxdoc-SGML をベースにしています。
現在 LDP では linuxdoc-sgml を継承・発展させた SGML-Tools を 標準として利用するようになってきており、それも linuxdoc-sgml と ある程度互換性のあった ver 1.0 から DTD (後述) を従来の Linuxdoc から DocBook に変更するなど linuxdoc-sgml とは 大きく異なる ver 2.0 に移行しています。
sgml-tools v1.09 までは過去との互換性を考慮して LinuxDoc DTD の 変換も可能となっていますが、sgml-tools v2.0 以降は DocBook DTD のみ であり、LinuxDoc DTD のサポートは打ち切られています。また v2.0 以降 ではテキストへの変換ツールがまだありません。現時点では Lynx の機能を 利用して SGML -> HTML -> Text へと変換する手順が推奨されている ようです。
一方 JF では現在 SGML-Tools 1.09 への日本語化パッチが用意されており、 SGML-Tools 1.09j として利用されています。この 1.09j では従来の jLinuxDoc-SGML に含まれていたコマンドとは異なり、日本語文書を変換する ためには "-l ja -c nippon" というオプションを指定する必要が あります。これを指定しなくても sgml2html による HTML への変換は可能だと いう情報もありますが、すくなくともテキストへの変換では上記のオプション を指定しないとうまく変換できないと思います。
なお、日本語化パッチの ver 2.0 への対応も要望されていますが、人手不足のため 作業は進んでいません。一方最近では LDP での sgml-tools の開発も、作者多忙の ために停滞しているようです。
SGML 文書の変換ツールには、 sgml-tool の他にも、 jade や doctools などの ソフトウェアがあります。例えば XFree86 では FreeBSD 関連のプロジェクトで 利用されてきた doctools というソフトウェアを利用して SGML 文書の変換を 行なっているようです。この doctools では LinuxDoc DTD な SGML 文書の変換 をサポートしていますが、こちらもテキストへの変換はうまく扱えないようです。
DTD 自体としては、LinuxDoc DTD がもともと LDP による独自規格で あるのに対して DocBook DTD は GNOME や KDE、FreeBSD などの プロジェクトでも使われており、技術文書の作成に広く利用されている 実績があって、図表の挿入も可能など機能的に優れていることから、 DocBook DTD への移行はそれなりに理由のあるものと言えます。
ただし、LDP でもまだ DocBook DTD を利用した HOW-TO や FAQ などは ほとんど見当たらず、従来からの LinuxDoc DTD を利用した文書が多いことを 考えると、LDP 文書の翻訳も作業のひとつである JF としては、 まだ LinuxDoc DTD のサポートを切り捨ててしまうわけにはいかないと 思われます。当面は sgml-tools 1.09j で LinuxDoc DTD な文書のサポートを 維持しながら、DocBook DTD の使い方について研究を進め、DocBook DTD の 利用ガイドや入門書などを整備するよう努力していくのが最善の方向では ないかと思われます。
今後の展開としては、DTD の DocBook への移行や sgml-tools あるいは それに代わるソフトウェアの日本語対応を進めていくのが良いでしょう。 できればオリジナルの状態で日本語サポートしてもらえるよう、パッチを レポートしてマージしてもらう方向に動きたいところです。
現時点では、DTD に Linuxdoc を利用してオリジナルの文書を作成するなら、 jLinuxdoc-SGML または sgml-tools 1.09j のどちらを使ってもそれほど違いは 無いでしょう。sgml-tools 1.09j では jLinuxdoc-SGML でサポートされていた いくつかの拡張が無くなっているので、過去の文書をそのまま利用する場合には jLinuxdoc-SGML のほうが楽かもしれません。
一方最新の LDP 文書を翻訳していく場合には、jLinuxdoc-SGML ではサポート されていない新しい機能を使う必要もあるため、sgml-tools 1.09j を利用する 必要があるでしょう。またオリジナル文書の作成でも DocBook DTD への移行に トライする場合には sgml-tools 1.09j を選択することになると思います。
なお、現在 sgml-tools 1.09j を使うには JF の Web site あるいは ftp site からオリジナルの sgml-tools-1.0.9.tar.gz のソースアーカイブと 日本語パッチの sgml-tools-1.0.9j.diff.gz を取得して自分で make する必要が あります。
2000. 1/7 更新: 現在、 JF Project によって「独自拡張」された Linuxdoc DTD の名前を LinuxdocTR DTD に変更し、あわせて sgml2latex の日本語対応や sgml2txt の bug fix などを行なったパッチとして diff.sgml-tools-1.0.9.jf6.gz を JF の Web サイトから公開しています。とりあえず Debian potato 用に 作業した結果から、Debian 独自の部分を取り除いたという状態なので、 RedHat 系/Slackware 系などの他のディストリビューションでは、現在動作 確認中です。試してみて結果をフィードバックしてくれる人を募集しています。
なお、JRPM には sgml-tools 1.09j のパッケージがあり、Vine Seed には これを利用したパッケージが含まれているとのことです。
また Debian potato には上記の diff.sgml-tools-1.0.9.jf6.gz を マージした sgml-tools_1.0.9-5 が登録されています。slink 向けには Debian JP の ftp site に experimental (実験的 = 公式ではない 配布物) として sgml-tools_1.0.9-4slink5 という名前で上記の potato 向け最新版を slink 用に合わせてリビルドしたパッケージが 置いてあります。 もし役に立つようでしたら、御自由にお使いください。
さて、jLinuxDoc-SGML では使えていたけれど、sgml-tools 1.09j では 使えなくなってしまった、というものにどのようなものがあるのか、を ここにまとめておきたいと思います。今のところ以下の点を見つけて いますが、他にもまだあるかもしれません。気づいた点があれば、 JF 宛に御連絡くださるか、JF の committer になって自分の手で直接 訂正してみてください。 よろしくお願いします。
jLinuxDoc-SGML では <hrule> を使うことで幅一杯の横線を 指定できましたが、 sgml-tools 1.09j ではサポートしていません。 この機能はもともとの LinuxDoc-SGML では含まれておらず、jLinuxDoc-SGML で 独自の拡張として追加されたものです。 同様な効果を得るには、「縦の間隔が広くあいた二重線」になって しまいますが、<CODE></CODE> を挿入する、という方法が あります。もし 2 つの <hrule> の間に文章を入れたい、という ことなら <CODE> と </CODE> の間に文章を書けば良いでしょう。
あるいは、「横線を引く」ことはできませんが、もし「線を引く」目的が 「文章の意味上、見た目を分離する必要がある」ということであれば、 本来は <sect>,<sect1>,<sect2> などの 「段落分け」や、<quote>,</quote> のような「引用」文の ためのタグをうまく使うようにするべきなのかもしれません。
jLinuxDoc-SGML では FAQ リストをまとめる際に便利なよう、 <faq> を使うことができましたが、sgml-tools 1.09j では これはサポートされていません。
また <faq> とあわせて指定することのできた <keyword>, <poster>, <pdate>, <question>, <answer>, <comment> などもすべて使えなくなっています。 御注意ください。
sgml2txt で SGML ファイルをテキストに変換すると、文書の末尾に 連続した空白行ができてしまいます。これを処理するために "cutblank" というコマンドが Linuxdoc-SGML に 用意されていたのですが、sgml-tools では無くなってしまいました。 このコマンドは以下に示す 12 行の perl スクリプトです。
#! /usr/bin/perl
$count = 0;
while (<STDIN>) {
if ($_ =~ /^$/) {
$count++;
} else {
$count = 0;
}
if ($count <= $ARGV[0]) {
print $_;
}
}
使い方は例えば "cat some.txt | cutblank 3" とすると 3 行以上の連続した空行をカットして標準出力に送ってくれる、 というものだと思います。
現在の SGML 変換ツール (sgml2html, sgml2txt) で日本語 SGML 文書を 変換する場合、EUC-JP コードでなければうまく扱えません。"kcc -c" でチェックしたり、Emacs/Mule での表示を確認するなどしておきましょう。 特に EUC-JP コード以外で作成された既存の文書をもとに SGML 化する際など うっかり忘れてしまうことがあるので、注意しましょう。
もとは「日本語版 Linuxdoc-SGML ガイド」に書いてある内容を、 ほぼそのまま写したものですが、JF ML で意見を頂いたおかげで いくつか増えています。
JF では多くの LDP 文書を日本語に翻訳していますが、その際、校正などに
便利なよう、原文をコメントとして訳文中に残すことが行なわれています。
ところが、SGML の仕様上コメント中に "--" を入れることはできません。
そこで原文をコメントアウトする際、 "--" を
"--" に変換する必要があります。
例えば
perl -e 'while(<>) { s/--/--/; s/^/<!-- O /; s/$/ -->; print; }'
などのコマンドを使って、あらかじめ原文全体をコメントアウトしてから
翻訳作業にかかると良いかもしれません。
以下の文字はそれぞれ右に示すように書いて下さい。 テキストや HTML へ変換する時に意図した文字に置き換えられます。 なお、西本さんの yasgml.el を Emacs/Mule と組み合わせて使えば、 この「書き換え」を自動的に行なってくれます。
~) → ˜[) → []) → ]&) → &<) → <>) → ></) → &etago;$) → $#) → #%) → %\) → \`` と ''
( " を表示させるには &dquot; )「わかった」と思っても、最初は意外と見落し易いものです。 もしチェックコマンド (sgmlcheck) でエラーになったら、ログの出力を リダイレクトして、しっかり見直しましょう。
さて、「使える文字」には、普通のかな、漢字、英数字に加えて 次の記号が含まれます。
: ; . , ? ! ` ' ( ) - / * @ ^ _ + = { } |
これらについては、本文中でなら普通に使ってしまって構いません。 ただし、 <author> のところでメールアドレスを書くために @ を そのまま使うとエラーになる場合があるみたいです。 (私はなりました。)
この場合はメールアドレスを <tt/user@domain/ のように <tt/ と / で囲むと良いようです。お試し下さい。
なお、「コメント中の "--"」 の個所も参照しておいてください。
以下のようなタグを覚えておくと便利でしょう。
HTML に変換した時に、クリックすると他の場所の URL へ ジャンプできるようにするためのタグです。
Web ブラウザで "JF (Japanese FAQ Project)" と表示されている
部分をクリックすることで、 <http://jf.linux.or.jp/> へ
ジャンプできるようにするには
<url url="http://jf.linux.or.jp/"
name="JF (Japanese FAQ Project)">
という風に書きます。
url の引数には、実際の URL を書きます。
また name の引数にはURL の名前や内容を書きます。
これはオプションなので、特に <url ... > タグを使う場合には
書かなくても問題無いです。
<url ... > と似たようなタグとして <htmlurl ... > が あります。<url ... > と <htmlurl ... > の違いは、 sgml2txt を使ってテキストに変換した際に URL が出力されるかどうかです。
例えば
という SGML ソースを sgml2html にかけると HTML のソースレベルで
に変換されます。一方 sgml2txt にかけると
のようになります。4 番目の例のような出力は、通常は誰も期待しない でしょうから、 <htmlurl ... > タグを使う場合は name= で 表示する文字列を指定してやる必要があります。
結局、Web 経由でアクセスできる文書などのように、テキスト中に URI を 示す必要がある場合には、<url ...> を使うほうが適切でしょう。 <htmlurl ...> のほうが適しているのは、メールアドレスを <mailto:> リンクしたり、ニュース記事 or ニュースグループを <news:> リンクしたりするような場合、と言えます。
箇条書きで使います。
例えば
SGML (jlinuxdoc-sgml) での箇条書きは
- 項目 1
- 項目 2
- 項目 3
こんな風になります。
<tt/SGML (jlinuxdoc-sgml)/ での箇条書きは
<itemize>
<item>項目 1
<item>項目 2
<item>項目 3
</itemize>
こんな風になります。
<itemize> を置き、
それぞれの項目の先頭に <item> を付けて、
最後に </itemize> で締めます。
箇条書き用には、他にも「見出しを付けた箇条書」のための
<descrip>
<tag>見出し(例)</tag>
</descrip>
や、「項目に番号を付けた箇条書」のための
<enum>
<item>ここに項目を書くと、それぞれの項目に番号がつく
</enum>
などがあります。
これらについては、「日本語版 Linuxdoc-SGML ガイド」の SGML 原稿 ファイルである jguide.sgml を JF の Web site から取得して じっくり調べてみると、いろいろ参考になるでしょう。
入力した文章を整形せずにそのまま出力されるためのタグです。 この 2 つのタグで囲まれた部分はそのまま出力されます。 ただし、 & と </ はこれでも使えませんので、それぞれ
&) → &ero;</) → &etago;を使って下さい。
<sect> の下をさらに分割する際に使います。 「節 (セクション)」の下の「小節 (サブセクション)」に 相当するものです。
ちなみに、 <sect> から <sect4> まで 5 段階の分割レベルが 用意されています。本文の前に <p> が必要なのはどの分割レベルでも 同じです。
強制的に改行させる場合に使います。使い過ぎに注意しましょう。
主に <sect>,<sect1> などの段落分けの見出し部分に 追加する、「相互参照」のためのタグです。これを <ref id=...> と 組み合わせることで、参照先のセクション番号を自動的に計算して 置き換える、といったことができます。HTML への変換では、これによって 該当個所へのリンクも設定されるようです。(未確認)
なお、HTML への変換では <htmlurl> のタグを使って相互参照を 実現することも可能です。これらについても詳細は「 日本語版 LinuxDoc-SGML ガイド 」を見てください。
です。なお、sgml2html では各 <sect> ごとに別の html ファイルに なりますが、サイズの小さな文書では全体をひとつの html ファイルに まとめたという場合もあります。そのような場合には sgml21html が 便利でしょう。sgml21html は JF の Web site から入手できます。
これらのコマンドを使う際は、例えば ``sgmlcheck anatano.sgml'' のように コマンド名のあとにスペースを入れて SGML のファイル名を指定します。
もし SGML についてもっと詳しく知りたければ、 まずは jlinuxdoc-sgml のソースに含まれている FAQj と jguide を 読むことをお勧めします。 この 2 つの文書はテキスト型式 (.txt) のものと SGML 型式 (.sgml) のものが 両方用意されているので、テキストを見ながら SGML を参照すると いろいろと書き方の参考になります。 ただし、これらの中で説明されているタグの中には、sgml-tools 1.0.9j では 使えないものがあることに注意してください。
現在、これらのファイルは JF の Web ページから
として読むことができます。
linuxdoc-sgml ではなく、SGML 一般については、 上記の JF のページ 日本語化 SGML-Tools による文書作成 から 「SGML 参考リンク集」を見ると参考になるでしょう。
SGML そのものについてではありませんが、sgml2html での出力について 検討する際など HTML についての知識が必要になる場合もあるかも しれませんので、JF ml で教えて頂いた参考資料を記載しておきます。
また、上記の JF のページには 「SGML 文書作成を支援するツール」として
も紹介されています。これ、私も最近多用していますが、非常に便利です。 まだ使ったことが無ければ、是非一度試してみることをお勧めします。
特にまだ SGML での文書作成に慣れていない人にとっては、 メニューから <sect> などの挿入を選択できる機能が とてもありがたいです。~ などの「使えない記号」は自動的に 変換して入力してくれます。
なお、Debian の開発版である potato には yasgml のパッケージが 含まれています。Debian ユーザーの方は、こちらをインストールすると 便利でしょう。
最近、Debian のメンバーである Stephane Bortzmeyer <bortzmeyer@pasteur.fr> が
特に
といったあたりは結構参考になりそうなので、読んでおくと ためになるかもしれません。なお最後の References には
が紹介されていました。前者は "A very good and practical book about the tools needed to write and process SGML on Unix and Windows NT. Does not cover XML. A very good chapter about Emacs' SGML mode, psgml and a nice page of PSGML tricks." また後者は "I didn't read it yet. The entire book is also online." と コメントされています。
また、以前 debian-sgml@lists.debian.org ML で教えてもらったのですが、 以下の場所に DocBook DTD の解説などがあるようです。
あと、 SGMLtools v2 の
sgmltools -b ld2db
を実行すると、LinuxDoc DTD な SGML 文書を DocBook DTD に変換してくれる らしいです。ただしまだ完全ではないので、変換後の修正は必要だとのこと。 sgmltools v2 と sgml-tools v1 を両方使える環境の人は、試してみると 良いでしょう。
(すくなくとも Debian potato では sgml-tools パッケージと sgmltools-2 パッケージ、それに jade が共存できるように作成されています。)
また、jade の使い方についてのサンプルが以下の場所にあるようです。
この文書は JF 全体の共有財産として育てて頂きたいので、 JF プロジェクトに参加して committer に登録された方は JF の CVS レポジトリにあるオリジナルの文書を自由に改変して くださって結構です。その際は最後の "CREDITS" の ところにお名前を変更個所を追記しておいてください。
この文書は LTGP 用に書いた SGML Memo に対して、JF ML でいろいろと 内容追加を要望してくださった川岸さんの御意見にヒントを得て、 「JF 文書作成用」のレファレンスとして使ってもらいたいという希望のもとで、 作成したものです。
文書の内容は「日本語版 Linuxdoc-SGML ガイド」から頂いてきたものを 中心に、JF ML で頂いた多くの有益なヒントをまとめたものです。 いろいろと有益な情報をくださった JF 参加者のみなさんに感謝します。
copyrighted (c) 1999 Taketoshi Sano
この文書は GNU パブリックライセンス (GPL) バージョン 2 かそれ以降 の条件、あるいは標準的な Linux ドキュメントプロジェクト (LDP) の条件に 基づいた配布ならば自由にしていただいてかまいません。これらのライセンス はこのドキュメントが入手できるようなサイトから入手できます。LDP の条件は (翻訳をのぞく) いかなる修正も許可していません。修正されたバージョンは GPL の基でのみ配布されるものとすることが可能です。
kgh12351@nifty.ne.jp) : 最初の雛型を作成