  SGML メモ (SGML 事始)
  佐野武俊 / Taketoshi Sano, (kgh12351@nifty.ne.jp)
  $Date: 2000/07/25 01:17:23 $

  この文書は初めて 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 <sect1>
     4.2 <newline>
     4.3 <verb> と </verb>
     4.4 <itemize> と </itemize>
     4.5 <url ... >

  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)
  <http://metalab.unc.edu/LDP/> や JF (Japanese FAQ) Project
  <http://www.linux.or.jp/JF/> などで以前使われていた Linuxdoc-SGML およ
  びその日本語化版 jLinuxdoc-SGML をベースにしています。

  現在 LDP では linuxdoc-SGML を継承・発展させた SGML-Tools を標準の変換
  ツールとして利用しているようです。

  これを受けて JF でも現在 SGML-Tools 1.09 への日本語化パッチが用意され
  ており、SGML-Tools 1.09j として利用されています。

  (2000 6/30 追加: SGMLTools の開発者である Cees de Groot が SGMLTools
  (v2) の開発を打ち切り、SGMLtool-Lite に移行したのを受け、LinuxDoc DTD
  専用ツールとして linuxdoc-tools の開発をスタートしました。今後は sgml-
  tools 用のパッチの開発ではなく linuxdoc-tools の開発を進めていきま
  す。)

  これらについては JF Project <http://www.linux.or.jp/JF/> によって配布
  されている SGML Tips for JF
  <http://www.linux.or.jp/JF/JFdocs/sgmlnote.html> を参照してください。

  2.  基本型 (全体の枠組)

  2.1.  doctype, article

  実は SGML というのは非常に柔軟な道具であって、

       Document Type Definition ``DTD''

  (日本語訳は「文書型定義」だそうです) というテンプレートのようなものを
  作成することで、いろんな書式に対応できます。

  が、ここでは「 LTGP 向けの文書を作成する」という目的がありますから、
  JF (Japanese FAQ Project) で開発された jLinuxdoc-SGML という型式に従っ
  て書きます。

  この場合、最初の行に

       <!doctype linuxdoc system>

  と書き、次の行に

       <article>

  さらに最後の行に

       </article>

  と書くというのが「お約束」です。まとめると

       <!doctype linuxdoc system>
       <article>
       (本文)
       </article>

  です。

  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 :) これを
     指定すると、あとでテキストに変換した場合、その位置で一行あけて段落
     わけされます。また各節の中で本文を書き始める前には、必ずこれを指定
     します。

  使用例はこんな感じになります。

       <title> テスト文書 (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  チルダ "~" (~)  → &tilde;

  o  左角かっこ ([) → &lsqb;

  o  右角かっこ (]) → &rsqb;

  o  アンパサンド (&) → &amp;

  o  左ブラケット (<) → &lt;

  o  右ブラケット (>) → &gt;

  o  左ブラケット＋スラッシュ (</) → &etago;

  o  ドルマーク ($) → &dollar;

  o  シャープ (#) → &num;

  o  パーセント (%) → &percnt;

  o  バックスラッシュ (\) → &bsol;

  o  二重引用符 → `` と '' ( " を表示させるには &dquot; )

  「わかった」と思っても、最初は意外と見落し易いものです。

  もしチェックコマンド (sgmlcheck) でエラーになったら、ログの出力をリダ
  イレクトして、ちゃんと見直しましょう。

  それから、上記の右にある表記ですが、 ``;'' もその一部です。 ``&lt'' と
  だけ書いて「エラーになった」と騒がないようにしましょう (経験者は語
  る)。

  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://www.linux.or.jp/JF/> へジャンプできるようにするには

       <url url="http://www.linux.or.jp/JF/"
            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.  各ディストリビューションでのパッケージ名と場所

  「手っ取り早く使いたい」という人のためのバイナリパッケージ案内。

  (2000 6/30 追加: ここにある情報はすこし古くなっています。既に JF でも
  obsolete になっている jLinuxdoc-SGML のパッケージが紹介してあります
  が、現在は日本語版 SGML-Tools のパッケージが用意されているディストリ
  ビューションもあると思います。少なくとも Vine Seed と Debian potato に
  は日本語版 sgml-tools-v1 のパッケージが存在します。現在 linuxdoc-tools
  のパッケージはまだどこからも公式には出ていないはずですが、Debian
  potato 用の非公式パッケージは存在します。また近いうちに Kondara 用の
  パッケージが作成されるかもしれないという話も聞いています。今後の最新の
  情報については SGML Tips for JF
  <http://www.linux.or.jp/JF/JFdocs/sgmlnote.html> を参照してください。)

  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://www.linux.or.jp/JF/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://www.linux.or.jp/JF/JFdocs/sgmlnote.html> を参照し
  てください。

  7.  参考文献など

  7.1.  SGML Note

  この文書では「初めての人」を対象に書いたので、いろいろと省略した部分な
  どもあります。もっと詳しく知りたい人は

  SGML Tips for JF <http://www.linux.or.jp/JF/JFdocs/sgmlnote.html>

  に記載されている「参考文献」の項目を参照してください。

  7.2.  便利なツール

  JF の Web サイトにある日本語化 SGML-Tools による文書作成
  <http://www.linux.or.jp/JF/workshop/guidance-sgml.html> というページに
  は「SGML 文書作成を支援するツール」として yasgml.el
  <http://www.linux.or.jp/JF/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 General Public License (GPL) バージョン 2 かそれ以降の
  条件、あるいは標準的な Linux ドキュメントプロジェクト (LDP) の条件に基
  づいた配布ならば自由にしていただいてかまいません。これらのライセンスは
  このドキュメントが入手できるようなサイトから入手できます。LDP の条件は
  (翻訳をのぞく) いかなる修正も許可していません。修正されたバージョンは
  GPL の基でのみ配布されるものとすることが可能です。

