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 を御参照ください。

1. SGML と DTD

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

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

4. LinuxDoc DTD の修飾 (タグ)

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

6. 参考文献など

7. おわりに


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 をベースにしたものであり、 日本語対応のための変更などが加えられています。

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 で入手できます。

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

日本語コードは 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 化する際などに、 うっかり忘れてしまうことがあるので、注意しましょう。

LinuxDoc-Tools のコマンド

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

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

その他の 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 がマルチバイトに対応していないこと、などがあります。

DocBook のツール

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

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

なお、この章内の html 出力までを行うツールに関する情報は、 LDP Authors Guide ( 原文) からの抜粋です。個々のインストールに関する詳細は、 LDP Authors Guide をご覧ください。

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 を、まずインストールしてください。

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 にあることを 指定しています。

DocBook DTD

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

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

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

ISO8879 ENTITY SGML

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

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

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

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

openjade

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

w3m

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

./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 で構いません。

RPM によるインストール

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

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

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

変換のコマンド

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 ( 原文)をご覧ください。

ディストリビューションのパッケージですべてインストールした場合、 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/> から、入手可能です。」
となります。

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

PSGML

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

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

使い方は、 LDP Authors Guide の編集ツールをご覧ください。

翻訳にあたって

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

原文の最初の方に

  <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>

日本語での著作者表記

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

  <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">

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 です。

変換のコマンド

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 ソースになります。

上記で、&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 入門LDP-Author-Guide( 原文) もしくは DocBook Definitive Guide をご覧ください。

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

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

例えば

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

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

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

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

4.2 <itemize> と </itemize>

箇条書きで使います。

例えば

SGML (LinuxDoc) での箇条書きは こんな風になります。
と出力したい場合は
<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 つのタグで囲まれた部分はそのまま出力されます。 ただし、 & と </ はこれでも使えませんので、それぞれ

を使って下さい。

4.4 <sect1>

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

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

4.5 <newline>

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

4.6 <label id=...>

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

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

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 をご覧ください。

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 をご覧ください。

6. 参考文献など

6.1 FAQ およびガイド

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

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

日本語版 LinuxDoc-SGML に関するQ&A

日本語版 LinuxDoc-SGML ガイド

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

6.2 SGML 一般について

LinuxDoc-SGML ではなく、SGML 一般については、 上記の JF のページ JF Workshop Guidance: SGML 文書作成 の中の SGML 参考リンク集 を見ると参考になるでしょう。

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

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

特にまだ 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 Contributors

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