SGML Tips for JF

JF Project, (`http://jf.linux.or.jp/`)

$Date: 2000/02/13 06:57:08 $

この文書は JF ML で SGML を利用して文書の作成・翻訳をする際に覚えておくと便利なこと、注意するべきことなどをまとめたものです。 SGML を使って文書を作成する際の基本的な約束については、 JF にある SGML Memo を御参照ください。

2. jLinuxDoc-SGML と sgml-tools 1.09j について

2.1 <hrule>
2.2 <faq>
2.3 "cutblank"

5. 修飾 (タグ)

5.1 <url ... > or <htmlurl ... >
5.2 <itemize> と </itemize>
5.3 <verb> と </verb>
5.4 <sect1>
5.5 <newline>
5.6 <label id=...>

1. SGML 文書変換ツールについて

以前から 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 用に合わせてリビルドしたパッケージが置いてあります。もし役に立つようでしたら、御自由にお使いください。

2. jLinuxDoc-SGML と sgml-tools 1.09j について

さて、jLinuxDoc-SGML では使えていたけれど、sgml-tools 1.09j では使えなくなってしまった、というものにどのようなものがあるのか、をここにまとめておきたいと思います。今のところ以下の点を見つけていますが、他にもまだあるかもしれません。気づいた点があれば、 JF 宛に御連絡くださるか、JF の committer になって自分の手で直接訂正してみてください。よろしくお願いします。

2.1 <hrule>

jLinuxDoc-SGML では <hrule> を使うことで幅一杯の横線を指定できましたが、 sgml-tools 1.09j ではサポートしていません。この機能はもともとの LinuxDoc-SGML では含まれておらず、jLinuxDoc-SGML で独自の拡張として追加されたものです。同様な効果を得るには、「縦の間隔が広くあいた二重線」になってしまいますが、<CODE></CODE> を挿入する、という方法があります。もし 2 つの <hrule> の間に文章を入れたい、ということなら <CODE> と </CODE> の間に文章を書けば良いでしょう。

あるいは、「横線を引く」ことはできませんが、もし「線を引く」目的が「文章の意味上、見た目を分離する必要がある」ということであれば、本来は <sect>,<sect1>,<sect2> などの「段落分け」や、<quote>,</quote> のような「引用」文のためのタグをうまく使うようにするべきなのかもしれません。

2.2 <faq>

jLinuxDoc-SGML では FAQ リストをまとめる際に便利なよう、 <faq> を使うことができましたが、sgml-tools 1.09j ではこれはサポートされていません。

また <faq> とあわせて指定することのできた <keyword>, <poster>, <pdate>, <question>, <answer>, <comment> などもすべて使えなくなっています。御注意ください。

2.3 "cutblank"

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 行以上の連続した空行をカットして標準出力に送ってくれる、というものだと思います。

3. 日本語コードは EUC-JP

現在の SGML 変換ツール (sgml2html, sgml2txt) で日本語 SGML 文書を変換する場合、EUC-JP コードでなければうまく扱えません。"kcc -c" でチェックしたり、Emacs/Mule での表示を確認するなどしておきましょう。特に EUC-JP コード以外で作成された既存の文書をもとに SGML 化する際などうっかり忘れてしまうことがあるので、注意しましょう。

4. 使える文字、使えない文字

もとは「日本語版 Linuxdoc-SGML ガイド」に書いてある内容を、ほぼそのまま写したものですが、JF ML で意見を頂いたおかげでいくつか増えています。

4.1 コメント中の "--"

JF では多くの LDP 文書を日本語に翻訳していますが、その際、校正などに便利なよう、原文をコメントとして訳文中に残すことが行なわれています。ところが、SGML の仕様上コメント中に "--" を入れることはできません。そこで原文をコメントアウトする際、 "--" を "--" に変換する必要があります。例えば

  perl -e 'while(<>) { s/--/&#045;&#045;/; s/^/<!-- O /; s/$/ -->; print; }'

などのコマンドを使って、あらかじめ原文全体をコメントアウトしてから翻訳作業にかかると良いかもしれません。

4.2 使えない文字

以下の文字はそれぞれ右に示すように書いて下さい。テキストや HTML へ変換する時に意図した文字に置き換えられます。なお、西本さんの yasgml.el を Emacs/Mule と組み合わせて使えば、この「書き換え」を自動的に行なってくれます。

チルダ "~" (~) → &tilde;
左角かっこ ([) → [
右角かっこ (]) → ]
アンパサンド (&) → &
左ブラケット (<) → <
右ブラケット (>) → >
左ブラケット＋スラッシュ (</) → &etago;
ドルマーク ($) → &dollar;
シャープ (#) → &num;
パーセント (%) → &percnt;
バックスラッシュ (\) → \
二重引用符 → `` と '' ( " を表示させるには &dquot; )

「わかった」と思っても、最初は意外と見落し易いものです。もしチェックコマンド (sgmlcheck) でエラーになったら、ログの出力をリダイレクトして、しっかり見直しましょう。

4.3 使える文字

さて、「使える文字」には、普通のかな、漢字、英数字に加えて次の記号が含まれます。


: ; . , ? ! ` ' ( ) - / * @ ^ _ + = { } |

これらについては、本文中でなら普通に使ってしまって構いません。ただし、 <author> のところでメールアドレスを書くために @ をそのまま使うとエラーになる場合があるみたいです。 (私はなりました。)

この場合はメールアドレスを <tt/user@domain/ のように <tt/ と / で囲むと良いようです。お試し下さい。

なお、「コメント中の "--"」の個所も参照しておいてください。

5. 修飾 (タグ)

以下のようなタグを覚えておくと便利でしょう。

5.1 <url ... > or <htmlurl ... >

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 が出力されるかどうかです。

例えば

<url url="http://case1.org" name="例 1">
<url url="http://case2.com">
<htmlurl url="http://case3.edu" name="例 3">
<htmlurl url="http://case4.gov">

という SGML ソースを sgml2html にかけると HTML のソースレベルで

<a href="http://case1.org">例1</a>
<a href="http://case2.com">http://case2.com</a>
<a href="http://case3.edu">例 3</a>
<a href="http://case4.gov"></a>

に変換されます。一方 sgml2txt にかけると

例 1 <http://case1.org>
<http://case2.com>
例 3
(何も出力されない)

のようになります。4 番目の例のような出力は、通常は誰も期待しないでしょうから、 <htmlurl ... > タグを使う場合は name= で表示する文字列を指定してやる必要があります。

結局、Web 経由でアクセスできる文書などのように、テキスト中に URI を示す必要がある場合には、<url ...> を使うほうが適切でしょう。 <htmlurl ...> のほうが適しているのは、メールアドレスを <mailto:> リンクしたり、ニュース記事 or ニュースグループを <news:> リンクしたりするような場合、と言えます。

5.2 <itemize> と </itemize>

箇条書きで使います。

例えば

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 から取得してじっくり調べてみると、いろいろ参考になるでしょう。

5.3 <verb> と </verb>

入力した文章を整形せずにそのまま出力されるためのタグです。この 2 つのタグで囲まれた部分はそのまま出力されます。ただし、 & と </ はこれでも使えませんので、それぞれ

アンパサンド (&) → &ero;
左ブラケット＋スラッシュ (</) → &etago;

を使って下さい。

5.4 <sect1>

<sect> の下をさらに分割する際に使います。「節 (セクション)」の下の「小節 (サブセクション)」に相当するものです。

ちなみに、 <sect> から <sect4> まで 5 段階の分割レベルが用意されています。本文の前に <p> が必要なのはどの分割レベルでも同じです。

5.5 <newline>

強制的に改行させる場合に使います。使い過ぎに注意しましょう。

5.6 <label id=...>

主に <sect>,<sect1> などの段落分けの見出し部分に追加する、「相互参照」のためのタグです。これを <ref id=...> と組み合わせることで、参照先のセクション番号を自動的に計算して置き換える、といったことができます。HTML への変換では、これによって該当個所へのリンクも設定されるようです。(未確認)

なお、HTML への変換では <htmlurl> のタグを使って相互参照を実現することも可能です。これらについても詳細は「日本語版 LinuxDoc-SGML ガイド」を見てください。

6. コマンド

文法チェックは sgmlcheck
テキストへの変換は sgml2txt -l ja -c nippon (v1.09j の場合)
HTML への変換は sgml2html -l ja -c nippon (v1.09j の場合。ただしオプション無しでも変換は可能らしい)

です。なお、sgml2html では各 <sect> ごとに別の html ファイルになりますが、サイズの小さな文書では全体をひとつの html ファイルにまとめたという場合もあります。そのような場合には sgml21html が便利でしょう。sgml21html は JF の Web site から入手できます。

これらのコマンドを使う際は、例えば ``sgmlcheck anatano.sgml'' のようにコマンド名のあとにスペースを入れて SGML のファイル名を指定します。

7. 参考文献など

7.1 FAQ およびガイド

もし SGML についてもっと詳しく知りたければ、まずは jlinuxdoc-sgml のソースに含まれている FAQj と jguide を読むことをお勧めします。この 2 つの文書はテキスト型式 (.txt) のものと SGML 型式 (.sgml) のものが両方用意されているので、テキストを見ながら SGML を参照するといろいろと書き方の参考になります。ただし、これらの中で説明されているタグの中には、sgml-tools 1.0.9j では使えないものがあることに注意してください。

現在、これらのファイルは JF の Web ページから

日本語版 Linuxdoc-SGML に関するＱ＆Ａ

日本語版 Linuxdoc-SGML ガイド

として読むことができます。

7.2 SGML 一般について

linuxdoc-sgml ではなく、SGML 一般については、上記の JF のページ日本語化 SGML-Tools による文書作成から「SGML 参考リンク集」を見ると参考になるでしょう。

7.3 HTML について

SGML そのものについてではありませんが、sgml2html での出力について検討する際など HTML についての知識が必要になる場合もあるかもしれませんので、JF ml で教えて頂いた参考資料を記載しておきます。

矢野啓介さん好ましい文書を書くための方法と考え方: http://www.asahi-net.or.jp/~wq6k-yn/konomac.html
矢野啓介さん HTMLのDTDを読んでみよう: http://www.asahi-net.or.jp/~wq6k-yn/readdtd.html
神崎正英さんのごく簡単なHTMLの説明: http://kanzaki.com/docs/htminfo.html
オンライン・ハイパーテキストのためのスタイルガイド: http://kanzaki.com/docs/Style/index.html

7.4 便利なツール

また、上記の JF のページには「SGML 文書作成を支援するツール」として

yasgml.el

も紹介されています。これ、私も最近多用していますが、非常に便利です。まだ使ったことが無ければ、是非一度試してみることをお勧めします。

特にまだ SGML での文書作成に慣れていない人にとっては、メニューから <sect> などの挿入を選択できる機能がとてもありがたいです。~ などの「使えない記号」は自動的に変換して入力してくれます。

なお、Debian の開発版である potato には yasgml のパッケージが含まれています。Debian ユーザーの方は、こちらをインストールすると便利でしょう。

7.5 DocBook DTD, jade

最近、Debian のメンバーである Stephane Bortzmeyer <[email protected]> が

The Debian SGML/XML HOWTO: http://www.debian.org/~bortz/SGML-HOWTO/

という文書を書いて公開しています。既に Debian/Debian JP メンバーの武藤さんが翻訳してくださって、 Stephane のところにも送ってあるのでそのうち日本語版も公開されるでしょう。

特に

What you really need to know about SGML: http://www.debian.org/~bortz/SGML-HOWTO/potato/x59.html
Creating documentation with DocBook: http://www.debian.org/~bortz/SGML-HOWTO/potato/x165.html
Creating documentation with LinuxDoc: http://www.debian.org/~bortz/SGML-HOWTO/potato/x255.html
References: http://www.debian.org/~bortz/SGML-HOWTO/potato/x384.html

といったあたりは結構参考になりそうなので、読んでおくとためになるかもしれません。なお最後の References には

SGML CD, Bob DuCHARME, Edited by Prentice-Hall, 0-13-475740-8: http://www.snee.com/bob/sgmlfree/
DocBook: The Definitive Guide, Norman Walsh, Leonard Muellner, Edited by O'Reilly, 1-56592-580-7: http://www.docbook.org/

が紹介されていました。前者は "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." とコメントされています。

また、以前 [email protected] ML で教えてもらったのですが、以下の場所に DocBook DTD の解説などがあるようです。

The DocBook DTD: http://www.oasis-open.org/docbook/
DocBook intro: http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html
Nik Clayton, FreeBSD Documentation Project Primer for New Contributors: http://www.freebsd.org/tutorials/docproj-primer/book.html
John Shipman, How to write documentation with DocBook: http://www.nmt.edu/tcc/help/pubs/docbook/t1.htm
John Fieber, DocBook Resources: http://fallout.campusview.indiana.edu/~jfieber/docbook/

あと、 SGMLtools v2 の

 sgmltools -b ld2db

を実行すると、LinuxDoc DTD な SGML 文書を DocBook DTD に変換してくれるらしいです。ただしまだ完全ではないので、変換後の修正は必要だとのこと。 sgmltools v2 と sgml-tools v1 を両方使える環境の人は、試してみると良いでしょう。

(すくなくとも Debian potato では sgml-tools パッケージと sgmltools-2 パッケージ、それに jade が共存できるように作成されています。)

また、jade の使い方についてのサンプルが以下の場所にあるようです。

an (English) example of jade usage: http://www.wi.LeidenUniv.nl/~jdassen/onderwijs/stuva/debug/

8. おわりに

この文書は JF 全体の共有財産として育てて頂きたいので、 JF プロジェクトに参加して committer に登録された方は JF の CVS レポジトリにあるオリジナルの文書を自由に改変してくださって結構です。その際は最後の "CREDITS" のところにお名前を変更個所を追記しておいてください。

この文書は LTGP 用に書いた SGML Memo に対して、JF ML でいろいろと内容追加を要望してくださった川岸さんの御意見にヒントを得て、「JF 文書瑳�蓿繙就�粮㏍芍��轣蛹≒鳫�笏蜿遐�竚癈鷭∂焜聨纃瘟赧漓�籬�㏍聽轣蛹就戟唄梶鬼碍霞⊂桿轣蛹Γ蔚飴頏阡繝�籟鹿畩」のレファレンスとして使ってもらいたいという希望のもとで、作成したものです。

文書の内容は「日本語版 Linuxdoc-SGML ガイド」から頂いてきたものを中心に、JF ML で頂いた多くの有益なヒントをまとめたものです。いろいろと有益な情報をくださった JF 参加者のみなさんに感謝します。

8.1 この文書の配布について

 copyrighted (c) 1999 Taketoshi Sano

この文書は GNU パブリックライセンス (GPL) バージョン 2 かそれ以降の条件、あるいは標準的な Linux ドキュメントプロジェクト (LDP) の条件に基づいた配布ならば自由にしていただいてかまいません。これらのライセンスはこのドキュメントが入手できるようなサイトから入手できます。LDP の条件は (翻訳をのぞく) いかなる修正も許可していません。修正されたバージョンは GPL の基でのみ配布されるものとすることが可能です。

8.2 CREDITS

佐野武俊 ([email protected]) : 最初の雛型を作成

sgml21html conversion date: Wed Feb 23 10:56:24 JST 2000

SGML Tips for JF

JF Project, (http://jf.linux.or.jp/)

JF Project, (`http://jf.linux.or.jp/`)