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