Taketoshi Sano, (kgh12351@nifty.ne.jp)
この文書は LDP (Linux Documentation Project) や JF (Japanese FAQ) Project などで以前使われていた Linuxdoc-SGML および その日本語化版 jLinuxdoc-SGML をベースにしています。
現在 LDP では linuxdoc-SGML を継承・発展させた SGML-Tools を 標準の変換ツールとして利用しているようです。
これを受けて JF でも現在 SGML-Tools 1.09 への日本語化パッチが 用意されており、SGML-Tools 1.09j として利用されています。 これらについては JF Project によって配布されている SGML Tips for JF を参照してください。
実は SGML というのは非常に柔軟な道具であって、
Document Type Definition ``DTD''
(日本語訳は「文書型定義」だそうです) というテンプレートの
ようなものを作成することで、いろんな書式に対応できます。
が、ここでは「 LTGP 向けの文書を作成する」という目的がありますから、
JF (Japanese FAQ Project) で開発された jLinuxdoc-SGML と
いう型式に従って書きます。
この場合、最初の行に
<!doctype linuxdoc system>
と書き、次の行に
<article>
さらに最後の行に
</article>
と書くというのが「お約束」です。まとめると
<!doctype linuxdoc system> <article> (本文) </article>
です。
最初に書いた doctype, article などは本文の外にある「大枠」ですが、 本文の中にも「必ず書いておくべき項目」というものがあります。 この項のタイトルになっている項目がそれで、以下のような意味があります。
使用例はこんな感じになります。
<title> テスト文書 (test article) <author> わたし <newline> <date> ver 0.1, テスト版 <abstract> ここには要約 (アブストラクト、サマリー) を書きます。 </abstract> <toc> <sect>最初の節 <p>節の中で本文を書くには、上のようにまず <sect> に 続けて <p> を書いて、その下から始めます。ちなみに <sect> の上にある <toc> は 「ここに目次を作って置いといてね」という意味で、 後でコマンドを使ってテキストや HTML に変換する時に 自動的に目次が作成されます。これは結構便利な機能です。
雰囲気はつかめたでしょうか ? あとは必要に応じて <sect> や <p> を追加していけば、どんどんと 長い文章を書いていける、というものです。
さてここで ``SGML'' で文章を書くときに気をつけなければ いけないことがひとつあります。
それは、 ``SGML'' で書く文章には「使える文字」と「使えない文字」が あるということです。ついでに書いておくと日本語コードは EUC を使うことに 決まっています。また行頭に . (ピリオド) や ' (アポストロフィ) が きてしまうと後で変換に使用するコマンドがうまく動作しなくなり、 きちんと出力できなくなるので、これらも避けましょう。
さて、「使える文字」には、普通のかな、漢字、英数字に加えて 次の記号が含まれます。
: ; . , ? ! ` ' ( ) - / * @ ^ _ + = { } |
これらについては、本文中でなら普通に使ってしまって構いません。 ただし、 <author> のところでメールアドレスを書くために @ を そのまま使うとエラーになる場合があるみたいです。 (私はなりました。)
この場合はメールアドレスを <tt/user@domain/ のように <tt/ と / で囲むと良いようです。お試し下さい。
以下の文字は、 SGML のコマンドとして解釈されてしまうので、それぞれ 右に示すように書いて下さい。テキストや HTML へ変換する時に意図した 文字に置き換えられます。
~) → ˜[) → []) → ]&) → &<) → <>) → ></) → &etago;$) → $#) → #%) → %\) → \`` と ''
( " を表示させるには &dquot; )「わかった」と思っても、最初は意外と見落し易いものです。
もしチェックコマンド (sgmlcheck) でエラーになったら、ログの出力を リダイレクトして、ちゃんと見直しましょう。
それから、上記の右にある表記ですが、 ``;'' も その一部です。 ``<'' とだけ書いて「エラーになった」 と騒がないようにしましょう (経験者は語る)。
さて、今までの部分だけで、とりあえずいくつかの節に分けて構成された 文章に、題名、作者、日付などの必要なヘッダーと目次を付けて ``SGML'' で 書けるようになったと思います。
この節は、もうちょっと文章表現に凝りたい、という人のための 使って便利なタグの紹介です。
「タグ」とは、今までに出てきた <sect> や <p> それに <title> などや <!doctype linuxdoc system> なども含めた、 < と > で囲まれた「項目指定」のことです。
例えば、以下のようなタグを覚えておくと便利でしょう。
<sect> の下をさらに分割する際に使います。 「節 (セクション)」の下の「小節 (サブセクション)」に 相当するものです。
ちなみに、 <sect> から <sect4> まで 5 段階の分割レベルが 用意されています。本文の前に <p> が必要なのはどの分割レベルでも 同じです。
強制的に改行させる場合に使います。使い過ぎに注意しましょう。
この文書は最初の頃、「使い過ぎに注意」と書いておきながら実は たくさん使っているという「悪い見本」になっていました。
文書の出来上がりを html に変換して kterm + lynx で確認したり、 text に変換して kterm + less で確認したりしていたのですが、 その環境で改行が単語の途中に挿入されたりすると妙に気になって 「外観」をコントロールしようとたくさん並べていたのです。
しかし、例えば Netscape Navigator でウィンドウサイズを 2, 3 度 変更しながら眺めていると、「改行にこだわる」のは無意味だな、と いうことが実感できました。
以上のような経過をたどって、この文書では途中から <newline> を 大幅にカットし、ほとんど使わないように心がけています。
入力した文章を整形せずにそのまま出力されるためのタグです。 この 2 つのタグで囲まれた部分はそのまま出力されます。 ただし、 & と </ はこれでも使えませんので、それぞれ
&) → &ero;</) → &etago;を使って下さい。
箇条書きで使います。
例えば
SGML (jlinuxdoc-sgml) での箇条書きは
- 項目 1
- 項目 2
- 項目 3
こんな風になります。
<tt/SGML (jlinuxdoc-sgml)/ での箇条書きは
<itemize>
<item>項目 1
<item>項目 2
<item>項目 3
</itemize>
こんな風になります。
<itemize> を置き、
それぞれの項目の先頭に <item> を付けて、
最後に </itemize> で締めます。
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 の名前や内容を書きます。
これはオプションなので、書かなくても問題無いです。
私は最初解説書 (jguide.txt) の「 sgmls がパーサー」 という部分だけ読んで、もろに ``sgmls sample.sgml'' を実行してしまい、 「おかしい。動かんぞ！どうなっているんだ。」などと騒いてしまいました。
実はあとでちゃんと読めば
ということが書いてあったのです。
こんな失敗をする奴がそうそういるわけも無いでしょうが、 一応、「このコマンドだけ覚えておけば大丈夫でしょう」と いうわけで、この節を書いておきます。
いいですね ? sgmlcheck/sgml2txt/sgml2html ですよ ? 覚えましたか ? (クドイって、、、)
ちなみに使い方は ``sgmlcheck anatano.sgml'' のように コマンド名のあとスペースを入れて SGML のファイル名を 指定します。
「手っ取り早く使いたい」という人のためのバイナリパッケージ案内。
パッケージ： main/text/linuxdoc-sgml-ja
Debian JP プロジェクトによってリリースされた追加パッケージである hamm-jp および slink-jp では ``linuxdoc-sgml-ja_1.5.1-5.deb'' が バイナリパッケージのファイル名になります。
パッケージ: contrib/Text/jlx-sgml.tgz
パッケージ: RPMS/jlinuxdoc-sgml-1.5-2.i386.rpm
バイナリパッケージがあるかどうかわかりませんでした。 御存知の方は教えて下さい。
以前は JF の Web ページ 日本語化 SGML-Tools による文書作成 から
を入手できたのですが、現在は LDP が既に linux-doc-sgml を 継承・発展させた新しいバージョンである SGML-Tools に移行しており、 翻訳の都合もあって JF でも SGML-Tools とその日本語化パッチしか 配布していません。
もし ftp サイトなどに見つからなければ上記の Debian または Plamo の 配布サイトからソースアーカイブを入手することが可能です。
この SGML Memo は「初めて SGML を使う人」を対象にしているため、 現在各ディストリビューションに収録されている jLinuxDoc-SGML に ついて主に説明しています。JF などでの作業のために SGML-Tools が 必要な場合には SGML Tips for JF を参照してください。
この文書では「初めての人」を対象に書いたので、いろいろと 省略した部分などもあります。もっと詳しく知りたい人は
に記載されている「参考文献」の項目を参照してください。
JF の Web サイトにある 日本語化 SGML-Tools による文書作成 というページには「SGML 文書作成を支援するツール」として yasgml.el が紹介されています。これ、私も最近多用していますが、非常に便利です。 まだ使ったことが無ければ、是非一度試してみることをお勧めします。
特にまだ SGML での文書作成に慣れていない人にとっては、 メニューから <sect> などの挿入を選択できる機能が とてもありがたいです。
なお、Debian の開発版である potato には yasgml のパッケージが 含まれています。Debian ユーザーの方は、こちらをインストールすると 便利でしょう。
これで「 SGML メモ」を終わります。え、簡単すぎるって ? 実は私もこれが SGML で書いた文章の第 2 弾です。 まことにすみませんが、これ以上高度なことはわかりません。
(実はその後いくつか SGML での文章作成を経験したので、 現在はこの文書を初めて作成した時よりも、すこしばかり 知識が増えたように思います。が、実はたいして変っていないかも。)
SGML の詳細については、既に充分親切に説明してある文献が世の中に あります。この文書はあくまでも「最初の一歩」の手助けになることを 期待して書かれています。
もし、「この表現はもっとこうしたほうがわかりやすいよ」とか 「実は私はこんな失敗をしたんだけど、これも追加して書いておいて くれないか」という要望があれば、遠慮なくメールで教えて下さい。
できれば LTGP の ML に参加して、あるいは JF ML に参加して、 それぞれ盛り上げてくれると、非常に嬉しいです。
私が SGML による文書作成を始めたのは 1998 年の暮に DebianTips という 文書を公開してもらおうと LTGP (Linux Total Guide Project) の ML へ 参加したのがきっかけでした。
このメモはその経験から、これから SGML での文章作成を始めようと している人を対象に、少しでも参考になればと思って書いたものです。
SGML (LinuxDoc DTD) での文書作成は、慣れてくれば全然難しいものでは ありません。なにか思いついたことがあれば、是非一度 SGML を使って 文章を書いてみてください。きっと便利な道具になると思います。
copyrighted (c) 1999 Taketoshi Sano
この文書は GNU パブリックライセンス (GPL) バージョン 2 かそれ以降 の条件、あるいは標準的な Linux ドキュメントプロジェクト (LDP) の条件に 基づいた配布ならば自由にしていただいてかまいません。これらのライセンス はこのドキュメントが入手できるようなサイトから入手できます。LDP の条件は (翻訳をのぞく) いかなる修正も許可していません。修正されたバージョンは GPL の基でのみ配布されるものとすることが可能です。