SGML Tips for JF
  JF Project, (http://www.linux.or.jp/JF/)
  $Date: 2002/11/12 11:04:15 $

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

  目次

  1. SGML と DTD
     1.1 SGML について
     1.2 DTD について

  2. SGML 文書変換ツールについて
     2.1 LinuxDoc および LinuxDocTR DTD
        2.1.1 LinuxDoc-Tools
           2.1.1.1 日本語コードは EUC-JP
           2.1.1.2 LinuxDoc-Tools のコマンド
        2.1.2 その他の LinuxDoc DTD 変換ツール
     2.2 DocBook DTD
        2.2.1 DocBook のツール
           2.2.1.1 DSSSL
           2.2.1.2 DocBook DTD
           2.2.1.3 ISO8879 ENTITY SGML
           2.2.1.4 openjade
           2.2.1.5 w3m
           2.2.1.6 RPM によるインストール
           2.2.1.7 変換のコマンド
           2.2.1.8 docbook-utils (Jade Wrapper) の使用
           2.2.1.9 PSGML
           2.2.1.10 翻訳にあたって
           2.2.1.11 日本語での著作者表記
     2.3 DocBook XML
        2.3.1 DocBook XML のツール
           2.3.1.1 変換のコマンド

  3. 使える文字、使えない文字
     3.1 コメント中の "--"
     3.2 LinuxDoc DTD で使えない文字
     3.3 LinuxDoc DTD で使える文字
     3.4 DocBook DTD で使えない文字
     3.5 LinuxDoc から DocBook への変換時の注意

  4. LinuxDoc DTD の修飾 (タグ)
     4.1 <url ... > or <htmlurl ... >
     4.2 <itemize> と </itemize>
     4.3 <verb> と </verb>
     4.4 <sect1>
     4.5 <newline>
     4.6 <label id=...>

  5. LinuxDoc DTD での画像の挿入と表組み
     5.1 画像の挿入
     5.2 表組み

  6. 参考文献など
     6.1 FAQ およびガイド
     6.2 SGML 一般について
     6.3 HTML について
     6.4 便利なツール
     6.5 DocBook DTD, jade

  7. おわりに
     7.1 この文書の配布について
     7.2 CREDITS

  ______________________________________________________________________

  1.  SGML と DTD

  1.1.  SGML について

  Standard Generalized Markup Language (標準汎用マークアップ言語) とは、
  文書をその構造、つまり章、節、段落など意味の上でのまとまり (これを
  element、構造化要素あるいは単に要素と呼びます。本文書ではエレメントと
  表記します。) を指定しながら記述するための方法のひとつです。 (SGML に
  は、データ交換などの用途もあります。)

  厳密に言えば、SGML 自体は「文書の構造を定義する」ものではなく、「文書
  の構造を定義する」ための DTD (文書型定義) を定義するための枠組を決めた
  ものです。つまり「SGML で文書を書く」際にはまずどの DTD を使うのか、あ
  らかじめ決めておかなければなりません。

  DTD にはいろいろな種類があります。例えば WWW (ワールドワイドウェブ) で
  利用されている HTML (この中にもいろいろな種類がありますが) も DTD で
  す。

  1.2.  DTD について

  DTD (文書型定義: Document Type Definition) というのは、SGML で文書を記
  述するために利用できる「構造」を規定したものです。

  例えば WWW で利用される HTML も SGML の一種であり、DTD として HTML
  3.2, HTML 4.0 Strict, HTML 4.01 Transitional などがあります。

  Linux 関連の文書では LinuxDoc DTD が以前からよく利用されてきましたが、
  これはもともと qwartz DTD (LaTeX 文書への変換に便利な DTD です) をもと
  に、LinuxDoc-sgml ツールの開発と合わせて作成されたものです。

  一方、最近では DocBook DTD を利用する例が増えてきています。印刷関連業
  界でも普及してきており、また Gnome, KDE などのフリーソフトウェア開発プ
  ロジェクトでも関連文書の作成に利用されています。 XFree86 の document
  でも従来は LinuxDoc DTD に変更を加えた独自の DTD を利用していたのです
  が、現在 DocBook DTD への移行が企画されています。さらに LinuxDoc DTD
  の本家本元の Linux Documentation Project (LDP) でも DocBook DTD への移
  行が本格的に進められています。

  DocBook DTD は、技術文書を SGML で作成する際の標準 DTD として多くの人
  々によって普及が推進されており、また LinuxDoc DTD では以前はサポートさ
  れていなかった図表の挿入が可能など機能的にも優れているので、移行はそれ
  なりに理由のあるものと言えます。

  DTD では、各エレメントの種類と、ある特定のエレメントの中にどんなエレメ
  ントを含むことができるかということ、また、エレメントの境界を示す「開始
  タグ」「終了タグ」のそれぞれについて省略可能であるかどうかということな
  どを規定しています。

  例えば LinuxDoc DTD では、"linuxdoc" というエレメント (開始タグ、終了
  タグともに省略可能) が文書全体を表現するエレメントであり、その中に
  sect、chapt、article、report、book などのエレメントを入れることができ
  ます。また article というエレメントの中には titlepage、header、
  toc、p、sect などのエレメントを入れることができます。

  エレメントの種類にはブロックエレメントとインラインエレメントがありま
  す。ブロックエレメントは上記の article、sect、chapt などの「意味のまと
  まり」を示すエレメント、インラインエレメントはテキスト自体のように文書
  の内容を示すエレメントと思っておけばよさそうです。

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

  2.1.  LinuxDoc および LinuxDocTR DTD

  現在 JF Project では、日本語の LinuxDoc DTD SGML 文書を変換処理するた
  めのツールとして、LinuxDoc-Tools を使用しています。このツールは、Cees
  de Groot による SGML-Tools の最後の LinuxDoc DTD 対応版である ver
  1.0.9 をベースにしたものであり、日本語対応のための変更などが加えられて
  います。
  2.1.1.  LinuxDoc-Tools

  SGML-Tools の後継である SGMLtools-Lite では、LinuxDoc DTD のサポートが
  廃止されてしまったので、DocBook への移行が完了するまでの暫定措置とし
  て、新たに LinuxDoc-Tools がリリースされることになりました。したがっ
  て、これから LinuxDoc DTD を使って文書を作成する場合は、LinuxDoc-Tools
  を使うようにしてください。

  LinuxDoc-Tools については、次のサイトをご覧ください。

  <http://people.debian.org/~sano/linuxdoc-tools/>

  JF では当初 jLinuxDoc-SGML というツールを使用していました。その
  後、SGML-Tools 1.0.9 に日本語パッチを当てた SGML-Tools 1.09j という
  ツールへと移行し、現在では LinuxDoc-Tools が使われています。jLinuxDoc-
  SGML から SGML-Tools への移行時に DTD の仕様が変更されたので、現在
  <hrule> や <faq> といった要素は使うことができません。

  この上記 LinuxDoc-Tools の SRPM が linuxdoc-tools-0.9.20-3.src.rpm
  <ftp://ftp.redhat.com/pub/redhat/linux/8.0/en/os/i386/SRPMS/linuxdoc-
  tools-0.9.20-3.src.rpm> で入手できます。

  RPM パッケージを使いたい場合は、これを試してみるとよいでしょう。

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

  注意点として、以前の jLinuxdoc-SGML ではオプションを指定しないでも日本
  語文書が扱えましたが、SGML-Tools 1.0.9 ベースのツールや LinuxDoc-Tools
  では、オプション "-l ja -c nippon "が必要になっています。これを指定し
  ないとちゃんと変換できません。

  また扱える日本語の文字コードは EUC-JP だけです。JIS コードや Shift-JIS
  ではうまく処理できません。 "kcc -c" でチェックしたり、Emacs/Mule での
  表示を確認しておきましょう。特に EUC-JP コード以外で作成された既存の文
  書をもとに SGML 化する際などに、うっかり忘れてしまうことがあるので、注
  意しましょう。

  2.1.1.2.  LinuxDoc-Tools のコマンド

  o  文法チェックは linuxdoc -B check -l ja -c nippon

  o  テキストへの変換は linuxdoc -B txt -l ja -c nippon -f

  o  HTML への変換は linuxdoc -B html -l ja -c nippon

  です。なお、linuxdoc -B html では各 <sect> ごとに別の html ファイルに
  なりますが、サイズの小さな文書では全体をひとつの html ファイルにまとめ
  たいという場合もあります。そのような場合には -s 0 -T 2 オプション
  や、sgml21html が便利でしょう。sgml21html は JF の Web site
  <http://www.linux.or.jp/JF/workshop/archives/sgml21html> から入手でき
  ます。

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

  2.1.2.  その他の LinuxDoc DTD 変換ツール

  LinuxDoc DTD を使った SGML 文書の変換ツールには、LinuxDoc-Tools の他に
  も doctools というソフトウェアがあります。例えば XFree86 では、FreeBSD
  関連のプロジェクトで利用されてきたこの doctools を利用して SGML 文書の
  変換が行なわれてきました。 doctools/XFree86 バージョン 1.1.3 以降では
  日本語への対応とともに、man ページフォーマットへの対応もなされていま
  す。

  2.2.  DocBook DTD

  JF では、DocBook SGML を HTML に変換するためのツールとして、openjade
  を使用しています。text へは html を経由して w3m で変換しています。現時
  点での問題は TeX、PS、PDF への出力で利用している jadetex が日本語対応
  していないためにこれらのフォーマットへの出力がちゃんとできないこと、お
  よび、LDP で PS, PDF への変換に利用されている HTMLDOC がマルチバイトに
  対応していないこと、などがあります。

  2.2.1.  DocBook のツール

  html 出力には openjade を、text 出力には openjade + w3m を用います。

  各ディストリビューションで用意されているパッケージでインストールする
  と、環境変数などの面倒な設定をする必要がないので、とても楽です。

  なお、この章内の html 出力までを行うツールに関する情報は、 LDP Authors
  Guide <http://www.linux.or.jp/JF/JFdocs/LDP-Author-Guide/index.html> (
  原文 <http://www.tldp.org/LDP/LDP-Author-Guide/index.html>) からの抜粋
  です。個々のインストールに関する詳細は、 LDP Authors Guide をご覧くだ
  さい。

  2.2.1.1.  DSSSL

  DSSSL (Document Style Semantics and Specification Language) は、どうい
  う方法で SGML 文書を印刷やオンライン用の文書にするかを openjade に指示
  するものです。たとえば、DSSSL に従って、title タグが、HTML では <H1>
  タグに変換され、RTF では 14 ポイントの Times Roman ボールド体に変換さ
  れます。 DSSSL に関する文書は下記の Norman Walsh DSSSL のページにあり
  ます。 DSSSL を修正することは、DocBook 自体を修正することにはならない
  点に注意してください。単にレンダリングされたテキストの見栄えを変えてい
  るにすぎません。

  通常の Walsh バージョンの DSSSL である Norman Walsh DSSSL
  <http://docbook.sourceforge.net/projects/dsssl/> を、まずインストール
  してください。

  Red Hat でのパッケージ名は docbook-style-dsssl、Debian でのパッケージ
  名は docbook-dsssl です。

  次に、jf-custom.dsl を
  <http://www.linux.or.jp/JF/workshop/archives/jf-custom.dsl> より入手し
  てください。

  jf-custom.dsl を、好きなディレクトリに置いてください。後述の説明のため
  /usr/local/share/sgml/stylesheets/ に置くことにします。

  ツール一式をソースからインストールした場合は、 jf-custom.dsl 内
  に、Walsh バージョンの DSSSL がどこにあるかを記述する必要があるかもし
  れません。

  ファイルの先頭部分を次のように書きかえます。 (注: openjade, DocBook,
  DSSSL スタイルシート, iso-entities を、ディストリビューションのパッ
  ケージでインストールした場合、書きかえは必要ありません)

    <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
  + <!--
    <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
  + -->
  + <!ENTITY docbook.dsl SYSTEM "/usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl" CDATA dsssl>
    ]>
    <style-sheet>

  上記では、Walsh バージョンの DSSSL が、
  /usr/lib/sgml/stylesheets/nwalsh-modular/html/docbook.dsl にあることを
  指定しています。

  2.2.1.2.  DocBook DTD

  文書の DTD のバージョン に合ったものを、 <http://www.oasis-
  open.org/docbook/sgml/> から入手します。

  Red Hat では、SGML/XML の DocBook DTD 一式が docbook-dtds パッケージに
  まとめられています。

  Debian では、SGML は docbook パッケージ、XML は docbook-xml パッケージ
  です。

  2.2.1.3.  ISO8879 ENTITY SGML

  ISO8879 ENTITY には、特殊な記号や文字の記述方法が定義されています。

  Red Hat では、sgml-common パッケージに含まれています。

  ソースからインストールする場合も、この sgml-common を利用するのが楽で
  す。 <ftp://sources.redhat.com/pub/docbook-tools/new-trials/SOURCES/>
  に、あります。

  Debian でのパッケージ名は、sgml-data です。

  2.2.1.4.  openjade

  html への変換に使用します。たいていのディストリビューションでは、バイ
  ナリパッケージが用意されています。ソースからインストールする場合は、
  openjade-1.3
  <http://download.sourceforge.net/openjade/openjade-1.3.tar.gz> を入手
  します。

  2.2.1.5.  w3m

  テキストへの変換に使用します。たいていのディストリビューションでは、バ
  イナリパッケージが用意されています。ソースからインストールする場合は、
  w3m <http://w3m.sourceforge.net/> を入手し、次のコマンドによりインス
  トールします。

  ./configure
  make
  make install

  ./configure で重要なのは、

  Which language do you prefer?
    1 - Japanese (charset ISO-2022-JP, EUC-JP, Shift_JIS)
    2 - English (charset US_ASCII, ISO-8859-1, etc.)
  [1]?

  と、

  Input your display kanji code.
          S - Shift JIS
          E - EUC-JP
          j - JIS: ESC $@ - ESC (J
          N - JIS: ESC $B - ESC (J
          n - JIS: ESC $B - ESC (B
          m - JIS: ESC $@ - ESC (B

  Which? E

  です。ブラウザ用途にしないのであれば、

  Let's do some configurations. Choose config option among the list.

  1 - Baby model    (no color, no menu, no mouse, no cookie, no SSL)
  2 - Little model  (color, menu, no mouse, no cookie, no SSL)
  3 - Mouse model   (color, menu, mouse, no cookie, no SSL)
  4 - Cookie model  (color, menu, mouse, cookie, no SSL)
  5 - Monster model (with everything; you need openSSL library)
  6 - Customize

  Which? 1

  で baby model を選び、他の質問には、enter で構いません。

  2.2.1.6.  RPM によるインストール

  openjade は、
  <ftp://rpmfind.net/linux/redhat/8.0/en/os/i386/RedHat/RPMS/openjade-1.3.1-9.i386.rpm>
  にあります。

  まず、次のパッケージがインストールされているか確認してください。

  o  sgml-common

  o  docbook-dtds

  o  docbook-style-dsssl

  Jade Wrapper は docbook-utils パッケージに含まれています。

  2.2.1.7.  変換のコマンド

  openjade, DocBook, DSSSL スタイルシート, iso-entities をソースからイン
  ストールした場合のみ、環境変数 SGML_CATALOG_FILES を適切に設定する必要
  があります。

  以下に一例を示します:

  export SGML_CATALOG_FILES=\
  /usr/local/share/sgml/iso-entities-8879.1986/iso-entities.cat:\
  /usr/local/share/sgml/docbk41/docbook.cat:\
  /usr/local/share/sgml/openjade-1.3/catalog:\
  /usr/local/share/sgml/docbook-dsssl-1.74b/catalog

  設定に関する詳細は、 LDP Authors Guide
  <http://www.linux.or.jp/JF/JFdocs/LDP-Author-Guide/jade.html> (原文
  <http://www.tldp.org/LDP/LDP-Author-Guide/jade.html>)をご覧ください。

  ディストリビューションのパッケージですべてインストールした場合、
  SGML_CATALOG_FILES の設定は不要です。

  分割された html 出力

  openjade -t sgml -i html \
     -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
       filename.sgml

  単一 html 出力

  openjade -t sgml -i html -V nochunks \
    -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
      filename.sgml > filename.html

  テキスト出力

  事前に単一の html ファイルを作ります。上述の方法では、ulink のリンク先
  が文字列として出力されないので、これを用いることはできません。

  「<ulink url="http://tldp.org/">LDP</ulink> から、入手可能です。」

  と SGML ソースに書いた場合、テキスト出力は、

  「LDP から、入手可能です。」

  になってしまいます。jf-custom.dsl はこれに対応するためのオプションを
  持っています。次のコマンドで、テキスト出力用の単一 html ファイルが作成
  できます。

  openjade -t sgml -i html -V nochunks -V %show-ulinks% \
    -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
      filename.sgml > filename.html

  次に作成したばかりの単一 html ファイルを用い、テキストに変換します。

  w3m -dump -T text/html -cols 72 -S filename.html > filename.txt

  前記の例で、テキスト出力は、

  「LDP <http://tldp.org/> から、入手可能です。」

  となります。

  2.2.1.8.  docbook-utils (Jade Wrapper) の使用

  docbook-utils (Jade Wrapper) を使うと、とても簡単に HTML や text に変
  換できます。

  入手方法

  RedHat, Debian, Slackware では、パッケージが用意されています。ソースは
  <ftp://sources.redhat.com/pub/docbook-tools/new-trials/SOURCES/> か
  ら、入手できます。

  使用方法

  分割された html 出力

  docbook2html -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
  filename.sgml

  単一 html 出力

  docbook2html -u -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
  filename.sgml

  テキスト出力

  docbook2txt -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
  filename.sgml

  2.2.1.9.  PSGML

  LinuxDoc 用に YaSGML を入れている場合は、モードを切り替えて使う必要が
  あります。

  <http://www.lysator.liu.se/~lenst/about_psgml/> から、入手できます。

  使い方は、LDP Authors Guide の編集ツール
  <http://www.linux.or.jp/JF/JFdocs/LDP-Author-Guide/editing.html>をご覧
  ください。

  2.2.1.10.  翻訳にあたって

  翻訳者の追記方法は、以下のようにします。

  原文の最初の方に

    <author>
     <firstname>Kevin</firstname>
     <surname>Taylor</surname>
     <affiliation>
       <address>
        <email>kevin@northants.lug.org.uk</email>
       </address>
     </affiliation>
    </author>

  とありますので、次のように変更します。

    <authorgroup>
     <author>
      <firstname>Kevin</firstname>
      <surname>Taylor</surname>
      <affiliation>
        <address>
         <email>kevin@northants.lug.org.uk</email>
        </address>
      </affiliation>
     </author>

     <othercredit role="translator" lang="ja">
      <surname>野本</surname>
      <firstname>浩一</firstname>
      <contrib>日本語訳</contrib>
      <affiliation>
        <address>
         <email>hng@ps.ksky.ne.jp</email>
        </address>
      </affiliation>
     </othercredit>
    </authorgroup>

  2.2.1.11.  日本語での著作者表記

  著作者を日本語で書く方法は、以下のようにします。

    <author lang="ja">
     <surname>野本</surname>
     <firstname>浩一</firstname>
     <affiliation>
       <address>
        <email>hng@ps.ksky.ne.jp</email>
       </address>
     </affiliation>
    </author>

  2.3.  DocBook XML

  LDP には、DocBook XML の文書も登録されています。冒頭の部分が以下のよう
  なものです。

    <?xml version="1.0"?>

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN">

  2.3.1.  DocBook XML のツール

  DocBook XML を HTML や text に変換するツールには、 openjade, xmlproc,
  cocoon などがありますが、現在 JF では DocBook SGML 同様に openjade を
  使っています。

  お使いの Linux ディストリビューションに、docbook2html コマンドなどを含
  む docbook-utils が用意されている場合は、これを使うのが一番簡単です。

  分割された html 出力

  docbook2html -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
  filename.xml

  以下は、openjade を直接使う場合を説明します。

  XML 用の DocBook が必要です。 <http://www.oasis-open.org/docbook/xml/>
  から、必要なバージョンのものを入手します。

  Debian の場合、パッケージ名は docbook-xml です。

  2.3.1.1.  変換のコマンド

  openjade, DocBook, DSSSL スタイルシート, iso-entities をソースからイン
  ストールした場合のみ、環境変数 SGML_CATALOG_FILES を XML 向けに再設定
  する必要があります。

  分割された html 出力

  文書ファイルの直前に、必ず xml.dcl を指定する必要があります。

  openjade -t sgml -i html \
       -d /usr/local/share/sgml/stylesheets/jf-custom.dsl \
       /usr/share/sgml/xml.dcl \
       filename.sgml

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

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

  3.1.  コメント中の "--"

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

  cat original.sgml | \
  perl -e 'while(<>) { s/--/&#045;&#045;/g; print; }' | \
  sed -e 's/^/<!-- 0 /' -e 's/$/ -->/' > commentout.sgml

  あるいは

  cat original.sgml | \
  perl -e 'while(<>){s/--/&#045;&#045;/g;s/^\s+$/ -->\n\n<!-- O \n/;print;}' \
   > commentout.sgml

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

  3.2.  LinuxDoc DTD で使えない文字

  LinuxDoc では、以下の文字はそれぞれ右に示すように書いて下さい。テキス
  トや HTML へ変換する時に意図した文字に置き換えられます。

  なお、LinuxDoc および LinuxDocTR では、西本さんの yasgml.el を
  Emacs/Mule と組み合わせて使うと、この「書き換え」を自動的に行なってく
  れます。

     チルダ "~" (~)
        → &tilde;

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

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

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

     左向き不等号 (<)
        → &lt;

     右向き不等号 (>)
        → &gt;

     左向き不等号＋スラッシュ (</)
        → &etago;

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

     シャープ (#)
        → &num;

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

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

     二重引用符 (")
        → &dquot;

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

  3.3.  LinuxDoc DTD で使える文字

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

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

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

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

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

  3.4.  DocBook DTD で使えない文字

  DocBook の場合、使えない文字は "<" と "&" だけです。

     左向き不等号 (<)
        → &lt;

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

  3.5.  LinuxDoc から DocBook への変換時の注意

  LinuxDoc DTD には、独自に拡張していた SGML エンティティがあります。こ
  れらは DocBook では使えません。次に示す変更を行うことにより、ほぼ、同
  等の変換出力が行える SGML ソースになります。

  o  &congr; →  =

  o  &dArr;  → &dArr;

  o  &dquot; → &quot;

  o  &ero;   → &amp;

  o  &etago; → &lt;&sol;

  o  &hArr;  → &hArr;

  o  &harr;  → &harr;

  o  &mid;   → &mid;

  o  &mu;    → &micro;

  o  &oplus; → &oplus;

  o  &otimes;→ &otimes;

  o  &setmn; → &setmn;

  o  &tm     → &trade;

  o  &uArr;  → &uArr;

  o  &vDash; → &vDash;

  o  &vdash; → &vdash;

  上記で、&setmn; &vDash; &vdash; の独自エンティティを同じ名前の ISO エ
  ンティティに置きかえていますが、

    "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN"
    "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN"

  などの ISO エンティティに定義されているもので、主に過去との互換性のた
  めに含まれているものと考えられ、実際にこれらのエンティティを利用した
  LinuxDoc 文書はほとんどないでしょう。

  どうしても必要な場合は Unicode を使ってそれぞれ &#x2216;, &#x22A2;,
  &#x22A8; とするか、あるいは特定のフォントに依存すること、またすこし形
  が違うことを承知のうえで、"\" (backslash)、"|-" (縦棒とハイフン)、
  "|=" (縦棒と等号) などで代用してください。

  また、独自エンティティとして、&urlnam; &refnam; も定義されていますが、
  これらは実装上の都合による中間処理のためのエンティティ定義なので、
  SGML ソースにこれらのエンティティを含めることは禁止されています。

  4.  LinuxDoc DTD の修飾 (タグ)

  この章の記述は、LinuxDoc DTD を使った場合の修飾タグです。 DocBook DTD
  を使う場合は、実用 DocBook 入門
  <http://www.linux.or.jp/JF/JFdocs/docbook-intro/>や LDP-Author-Guide
  <http://www.linux.or.jp/JF/JFdocs/LDP-Author-Guide/index.html>(原文
  <http://tldp.org/LDP/LDP-Author-Guide/index.html>) もしくは DocBook
  Definitive Guide <http://www.docbook.org/tdg/html/docbook.html> をご覧
  ください。

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

  4.1.  <url ... > or <htmlurl ... >

  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 の名前
  や内容を書きます。これはオプションなので、特に <url ... > タグを使う場
  合には書かなくても問題無いです。

  <url ... > と似たようなタグとして <htmlurl ... > があります。<url ...
  > と <htmlurl ... > の違いは、 sgml2txt を使ってテキストに変換した際に
  URL が出力されるかどうかです。

  例えば

  o  <url url="http://case1.org" name="例 1">

  o  <url url="http://case2.com">

  o  <htmlurl url="http://case3.edu" name="例 3">

  o  <htmlurl url="http://case4.gov">

  という SGML ソースを linuxdoc -B html にかけると HTML のソースレベルで

  o  <a href="http://case1.org">例1</a>

  o  <a href="http://case2.com">http://case2.com</a>

  o  <a href="http://case3.edu">例 3</a>

  o  <a href="http://case4.gov"></a>

  に変換されます。一方 linuxdoc -B txt にかけると

  o  例 1 <http://case1.org>

  o  <http://case2.com>

  o  例 3

  o  (何も出力されない)

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

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

  4.2.  <itemize> と </itemize>

  箇条書きで使います。

  例えば

       SGML (LinuxDoc) での箇条書きは

       o  項目 1

       o  項目 2

       o  項目 3

          こんな風になります。

  と出力したい場合は

       <tt/SGML (LinuxDoc)/ での箇条書きは
       <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 から取得してじっくり調べてみる
  と、いろいろ参考になるでしょう。

  4.3.  <verb> と </verb>

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

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

  o  左向き不等号＋スラッシュ (</) → &etago;

  を使って下さい。

  4.4.  <sect1>

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

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

  4.5.  <newline>

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

  4.6.  <label id=...>

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

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

  5.  LinuxDoc DTD での画像の挿入と表組み

  LinuxDoc においても画像や表を文書に組み込むことができます。どうしても
  必要な場合にお使いください。

  5.1.  画像の挿入

  画像を挿入したい場合は、<figure> が使えます。

       <figure>
       <ph vspace="0">
       <img src="ファイル名">
       </figure>

  上記設定を使うと、HTML 変換の場合は画像が挿入され、テキスト変換の場合
  はなにも表示されません。テキスト変換の際に代替テキストを表示させたい場
  合は、次のようにしてください。

       <#if output="html">
       <figure>
       <ph vspace="0">
       <img src="ファイル名">
       </figure>
       </#if>
       <#unless output="html">
       代替テキスト
       </#if>

  実例は、The-Linux-Kernel <http://www.linux.or.jp/JF/JFdocs/The-Linux-
  Kernel-2.html> をご覧ください。

  5.2.  表組み

  表組みには、<table> タグが利用できます。以下はその一例です。

  <#if output="html">
  <table loc="tbp">
  <tabular ca="ccc">
  列1 | 列2 | 列3 @
  内容1 | 内容2 | 内容3 @
  </tabular>
  </table>
  </#if>

  <#unless output="html">
  <descrip>
  <tag>列1</tag>内容1
  <tag>列2</tag>内容2
  <tag>列3</tag>内容3
  </descrip>
  </#if>

  表はテキスト変換時にエラーとなるので、必ず出力を分けて利用してくださ
  い。

  実例は、ISAPnP-HOWTO <http://www.linux.or.jp/JF/JFdocs/ISAPnP-
  HOWTO-3.html> をご覧ください。

  6.  参考文献など

  6.1.  FAQ およびガイド

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

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

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

        o  (HTML 版) <http://www.linux.or.jp/JF/workshop/linuxdoc-
           sgml/FAQj.html>

        o  (テキスト版) <http://www.linux.or.jp/JF/workshop/linuxdoc-
           sgml/FAQj.txt>

        o  (SGML 版) <http://www.linux.or.jp/JF/workshop/linuxdoc-
           sgml/FAQj.sgml>

     日本語版 LinuxDoc-SGML ガイド

        o  (HTML 版) <http://www.linux.or.jp/JF/workshop/sgml-
           jguide/jguide.html>

        o  (テキスト版) <http://www.linux.or.jp/JF/workshop/sgml-
           jguide/jguide.txt>

        o  (SGML 版) <http://www.linux.or.jp/JF/workshop/sgml-
           jguide/jguide.sgml>
  として読むことができます。

  6.2.  SGML 一般について

  LinuxDoc-SGML ではなく、SGML 一般については、上記の JF のページ JF
  Workshop Guidance: SGML 文書作成
  <http://www.linux.or.jp/JF/workshop/guidance-sgml.html> の中の SGML 参
  考リンク集 <http://www.linux.or.jp/JF/workshop/guidance-
  sgml.html#sgml-links> を見ると参考になるでしょう。

  6.3.  HTML について

  SGML そのものについてではありませんが、linuxdoc -B html での出力につい
  て検討する際など 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>

  6.4.  便利なツール

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

  yasgml.el
  <http://www.linux.or.jp/JF/workshop/archives/yasgml_1.5-5.tar.gz>

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

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

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

  6.5.  DocBook DTD, jade

  Debian のメンバーである Stephane Bortzmeyer <bortzmeyer@pasteur.fr> が

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

  という文書を書いて公開しています。Debian/Debian JP メンバーの武藤さん
  が翻訳してくださった日本語版もあります。

     日本語版 The Debian SGML/XML HOWTO
        <http://www.topstudio.co.jp/~kmuto/debian/Debian-HOWTO/potato/>

  特に

     あなたが実際に SGML について知る必要があること
        <http://www.topstudio.co.jp/~kmuto/debian/Debian-
        HOWTO/potato/x67.html>

     DocBook でドキュメントを作成
        <http://www.topstudio.co.jp/~kmuto/debian/Debian-
        HOWTO/potato/x174.html>

     LinuxDoc によるドキュメントの作成
        <http://www.topstudio.co.jp/~kmuto/debian/Debian-
        HOWTO/potato/x268.html>

     参照
        <http://www.topstudio.co.jp/~kmuto/debian/Debian-
        HOWTO/potato/x406.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." とコメントされています。

  また、以前 debian-sgml@lists.debian.org 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 Contribu-
        tors
        <http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/fdp-primer/>

     John Shipman, How to write documentation with DocBook 4.1
        <http://www.nmt.edu/tcc/help/pubs/docbook/>

  あと、 SGMLtools v2 の

  ______________________________________________________________________
   sgmltools -b ld2db
  ______________________________________________________________________

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

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

  7.  おわりに

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

  この文書は LTGP 用に書いた SGML Memo に対して、JF ML でいろいろと内容
  追加を要望してくださった川岸さんの御意見にヒントを得て、「JF 文書作成
  用」のレファレンスとして使ってもらいたいという希望のもとで、作成したも
  のです。

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

  7.1.  この文書の配布について

   Copyright (c) 1999 Taketoshi Sano
   Copyright (c) 2002 JF Project

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

  7.2.  CREDITS

  o  佐野武俊 (kgh12351@nifty.ne.jp) : 最初の雛型を作成

  o  千旦裕司 (ysenda@pop01.odn.ne.jp) : 画像と表組を追加

  o  野本浩一 (hng@ps.ksky.ne.jp) : DocBook のツールを追加

  o  小林雅典 (zap03216@nifty.ne.jp) : 現状にあわせて更新