JF-INDEX (document list of JF Project)

SGML Tips for JF

JF Project, (http://www.linux.or.jp/JF/)

$Date: 2002/01/09 16:25:06 $


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

1. SGML と DTD

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

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

4. 修飾 (タグ)

5. 画像の挿入と表組み

6. コマンド

7. 参考文献など

8. おわりに


1. SGML と DTD

1.1 SGML について

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

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

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

Linux 関連の文書では、今まで LinuxDoc DTD が使われている例が 多かったのですが、最近では印刷関連業界にも DocBook DTD が普及してきて、 また Gnome/KDE などのフリーソフトウェア開発プロジェクトでも関連文書の 作成に DocBook DTD を利用しています。XFree86 の document でも従来は LinuxDoc DTD に変更を加えた独自の DTD を利用していたのですが、現在 DocBook DTD への移行が企画されています。さらに LinuxDoc DTD の本家本元の Linux Documentation Project (LDP) でも DocBook 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 を利用する例が増えてきていますが、 これは技術文書を SGML で作成する際の標準 DTD として 多くの人々によって普及が推進されており、また LinuxDoc DTD では 以前はサポートしていなかった図表の挿入も可能など機能的に優れていることから、 DocBook 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 では、1.0.9 以降の後継バージョンでは、LinuxDoc DTD をサポートしないことが明確になったので、DocBook への 移行が完了するまでの暫定措置として LinuxDoc-Tools へと名称 を変更し、bug fix 版のみがリリースされることになりました。 したがって、これから LinuxDoc DTD を使って文書を作成する 場合は、LinuxDoc-Tools を使うようにしてください。

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

http://www.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> といった要素は現在利用できなくなっています。また日本語化パッチ sgml-tools-1.0.9.jf7.diff.gz にはバグがあることが確認 されています。したがって、なるべく上記 LinuxDoc-Tools を お使いください。

この上記 LinuxDoc-Tools の SRPM が linuxdoc-tools-0.9.1-0v13.src.rpm で入手できます。

また、少し以前のバージョンではありますが、diff.sgml-tools-1.0.9.jf6.gz を 使った SRPM sgml-tools-1.0.9_jp-6.2.src.rpm があります。こちらは最新版に比較するといくつかの機能が含まれていませんが、 基本的な動作に問題は無いはずです。もし RPM パッケージを使いたい場合には これらを試されてみると良いでしょう。

その他の LinuxDoc DTD 変換ツール

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

一方 LDP では最近 DocBook DTD SGML への移行が徐々に進められてきており、 変換処理のための jade を利用した Makefile が利用されています。また、 現在では DocBook XML 環境の整備もすすめられており、XML で記述された文書 も公開されています。

さらに、SGMLtools およびその後継である SGMLtools-Lite が LinuxDoc DTD の サポートを廃止してしまったので、公式に LinuxDoc DTD をサポートしている ツールは XFree86 の doctools しか無く、これについても DocBook DTD への 移行が進めば LinuxDoc DTD のサポートは廃止されてしまう可能性があるという ことで、過去の文書を利用できるようにするために SGML-Tools v1 ベースの 新しいコードとして LinuxDoc-Tools を開発していくことを計画中です。 (これがリリースできれば LDP からも公式ツールとして利用されるようになる はずです。なお、LinuxdocTR として区別した <trans>、<tdate> などの要素も LinuxDoc-Tools では LinuxDoc DTD の中に入れてしまおうかと 考えています。このへんは XFree86 の doctools へのパッチの方向とも絡んで いるので詳しい説明は省略します。)

日本語コードは 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.2 DocBook DTD

DocBook DTD の処理ツールである jade などでは特に EUC-JP な日本語文書に ついても html への変換に限れば問題は無いようです。text への変換も html を経由して w3m で実行するため問題ありません。 現時点での問題は TeX、PS、PDF への出力で利用している jadetex が日本語対応していないために これらのフォーマットへの出力がちゃんとできないこと、および、LDP で PS, PDF への変換に 利用されている HTMLDOC がマルチバイトに対応していないこと、などがあります。

JF での今後の展開としては、DocBook DTD な文書の変換処理について LDP での議論を参考にしながら決めていくことなどが必要になると思われます。

DocBook のツール

現状、単一および複数の html 出力と text 出力が行えています。 html 出力には、jade を、text 出力には、jade + w3m を用います。

この文書内の html 出力までを行うためのツールに関する情報は、 LDP Authors Guide ( 原文) からの抜粋です。詳細は、LDP Authors Guide をご覧ください。

DSSSL

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

通常の Walsh バージョンの DSSSL である Norman Walsh DSSSL を、まず、入手してください。

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

jf-custom.dsl 内に、Walsh バージョンの DSSSL がどこにあるか記述します。 ファイルの先頭部分を次のように書きかえます。 </

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

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

DocBook DTD

DocBook は、v4.1 もリリースされていますが、 現在 (2001/03/25)、JF では、未対応です。

これは、JF のビルド環境が Debian potato を利用していて、potato に DocBook 4.1 のパッケージが無かったからです。

バージョン 3.1 を入手します。

Jade

html への変換に使用します。 Jade を入手し、インストールします。

w3m

テキストへの変換に使用します。 w3m のバージョン 0.2.1 を入手し、次のコマンドにより、インストー ルします。

./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 によるインストール

jade は、 jade-1.2.1-9j1.i386にあります。

Jade wrapper は、cygnus-tools として、Red Hat 6.2 に付属しています。まず、 次のパッケージがインストールされているか確認してください。

最新バージョンは、 Red Hat のウェブサイトにあります。

変換のコマンド

分割された html 出力

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

単一 html 出力

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

テキスト出力

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

「<ulink url="http://www.linuxdoc.org/">LDP</ulink> から、入手可能
です。」
というように SGML ソースに書いた場合、テキスト出力は、
「LDP から、入手可能です。」
となってしまいます。jf-custom.dsl はこれに対応するためのオプションを持っ ています。次のコマンドで、テキスト出力用の単一 html ファイルを作成します (filename.html だったとします)。
jade -t sgml -i html -V nochunks -V "%show-ulinks%" \
  -d /usr/local/lib/sgml/stylesheets/jf-custom.dsl \
    filename.sgml > filename.html
前記の例で、テキスト出力は、
「LDP ("http://www.linuxdoc.org/") から、入手可能です。」
となります。

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

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

cygnus tools の使用

db2html を使うと、サブディレクトリを作成し、その中に、分割された html に 変換してくれます。

入手方法

jf-custom.dsl を使用するように、db2html の先頭部分を次のよう編集します。

  #! /bin/sh

+ <!--
  DB_STYLESHEET=/usr/lib/sgml/stylesheets/cygnus-both.dsl
+ -->
+ DB_STYLESHEET=/usr/local/lib/sgml/stylesheets/jf-custom.dsl
  HTML_STYLESHEET=/usr/lib/sgml/stylesheets/nwalsh-modular/test/docbook.css

サブディレクトリへの分割 html 出力は、

db2html filename.sgml
とします。filename というディレクトリの下に出力されます。

db2html で分割 html, テキストを一度に作成する場合は、 上記の編集に次いで、ファイルの真ん中あたりを以下のように編集します。

  # we used to generate a single file, but with the modular DB_STYLESHEETs
  # it's best to make a new directory with several html files in it
  #cat $* | jade -d $DB_STYLESHEET -t sgml -V nochunks > $TMPFN
+ cat $* | jade -d $DB_STYLESHEET\#html -t sgml -i html \
+   -V nochunks -V "%show-ulinks%" | \
+     w3m -T text/html -S -dump -cols 72 > $output.txt

使用方法は、

db2html filename.sgml
で、同じディレクトリに filename.txt が、 filename というディレクトリの下に複数html出力されます。

書き換えた db2html を /usr/bin/db2jf として使うといいかもしれません。

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">
    <firstname>浩一</firstname>
    <surname>野本</surname>
    <contrib>日本語翻訳</contrib>
    <affiliation>
      <address>
       <email>hng@ps.ksky.ne.jp</email>
      </address>
    </affiliation>
   </othercredit>
  </authorgroup>

漢字での著作者表記

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

  <author lang="ja">
   <firstname>浩一</firstname>
   <surname>野本</surname>
   <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" [

XML 形式は、空エレメント (<xref id="xxx"/> など <hoge></hoge> の形式になっていないやつ)の扱いを除いて、 SGML DocBook と同じはずなので、冒頭の部分を

  <!doctype article public "-//OASIS//DTD DocBook V3.1//EN" [

に書きかえます。実際には、XML の文書型宣言はコメントアウトして、DocBook SGML V3.1 に修正してください。

また、<articleinfo> および </articleinfo> があった場合は、そ れぞれ、<artheader>, </artheader> に書きかえます。

それでも、jade がエラーする場合には、JF-ML に質問しましょう。


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 使えない文字

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

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

DocBook の場合、現在の変換処理系 (jade + w3m) で、使えない文字は "<" と "&" だけですが、今後処理系が充実していく ことを鑑み、このルールに従っておくことをお勧めします。

チルダ "~" (~)

左角かっこ ([)

&lsqb;

右角かっこ (])

&rsqb;

アンパサンド (&)

&amp;

左向き不等号 (<)

&lt;

右向き不等号 (>)

&gt;

左向き不等号+スラッシュ (</)

ドルマーク ($)

&dollar;

シャープ (#)

&num;

パーセント (%)

&percnt;

バックスラッシュ (\)

&bsol;

二重引用符 (")

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

3.3 使える文字

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

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

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

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

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

3.4 LinuxDoc から DocBook への変換時の注意

LinuxDoc DTD には、独自に拡張していた SGML エンティティがあり、DocBook DTD で、そのままでは使えません。次に示す変更を行うことにより、ほぼ、同等 の変換出力が行える 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 を使った場合の修飾タグです。 DocBook DTD を使う場合は、docbook-intro や LDP-Author-Guide( http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html name="原文">) もしくは 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 が出力されるかどうかです。

例えば

という SGML ソースを sgml2html にかけると HTML のソースレベルで

に変換されます。一方 sgml2txt にかけると

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

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

4.2 <itemize> と </itemize>

箇条書きで使います。

例えば

SGML (jLinuxDoc-SGML) での箇条書きは こんな風になります。
と出力したい場合は
<tt/SGML (jLinuxDoc-SGML)/ での箇条書きは
<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 においても画像や表を文書に組み込むことができます。 どうしても必要な場合にお使いください。

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. コマンド

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

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


7. 参考文献など

7.1 FAQ およびガイド

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

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

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

日本語版 LinuxDoc-SGML ガイド

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

7.2 SGML 一般について

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

7.3 HTML について

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

7.4 便利なツール

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

yasgml.el

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

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

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

7.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 メンバーの 武藤さんが翻訳してくださって、 Stephane のところにも送ってあるので そのうち日本語版も公開されるでしょう。

特に

What you really need to know about SGML

http://www.debian.org/~bortz/SGML-HOWTO/potato/x59.html

Creating documentation with DocBook

http://www.debian.org/~bortz/SGML-HOWTO/potato/x165.html

Creating documentation with LinuxDoc

http://www.debian.org/~bortz/SGML-HOWTO/potato/x255.html

References

http://www.debian.org/~bortz/SGML-HOWTO/potato/x384.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/tutorials/docproj-primer/book.html

John Shipman, How to write documentation with DocBook

http://www.nmt.edu/tcc/help/pubs/docbook/t1.htm

John Fieber, DocBook Resources

http://fallout.campusview.indiana.edu/~jfieber/docbook/

あと、 SGMLtools v2 の


 sgmltools -b ld2db

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

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

また、jade の使い方についてのサンプルが以下の場所にあるようです。

an (English) example of jade usage

http://www.wi.LeidenUniv.nl/~jdassen/onderwijs/stuva/debug/


8. おわりに

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

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

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

8.1 この文書の配布について

 copyrighted (c) 1999 Taketoshi Sano

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

8.2 CREDITS


sgml21html conversion date: Thu Jan 10 02:06:19 JST 2002