3. SGML で文書を書くには

ここでは linuxdoc.dtd を使った文書の書き方について説明します。

3.1 文書の始め方

一番最初に覚えなければならないことを簡単に書きます。

SGML ファイルの最初

SGML では (コメントは別にして) 必ず

<!doctype linuxdoc system>

使用する文字

入力に使用できるキャラクタとしては、かな、漢字、英数字、および次の記号 です。

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

【注意】 jlinuxdoc-sgml では、EUC 漢字コードを使うようになっていますので、EUC コードで文書を書くようにして下さい。 また、半角カナと呼ばれている文字は使えません。

【注意】行頭を . で始めますと、テキストに変換する際に、問題が発生 します。よって、行頭には . を記述しないようにして下さい。

特殊文字

SGML では、以下の記号をコマンドとして認識してしまいますので、その記号 を文字として使いたい場合には下のように入力して下さい。

• 左角かっこ ([) を使うには [ と入 力します
• 右角かっこ (]) を使うには ] と入 力します
• アンパサンド (&) を使うには & と入 力します
• 左ブラケット (<) を使うには < と入力 します
• 右ブラケット (>) を使うには > と入力 します
• 左ブラケット＋スラッシュ (</) を使うには &etago; と入力します
• ドルマーク ($) を使うには $ と入力します
• シャープ (#) を使うには # と入力し ます
• パーセント (%) を使うには % と入力します
• バックスラッシュ (\) を使うには \ と入力します
• 二重引用符を使うには `` と '' と入力するか、 " を表示させるには &dquot; と入力します

3.2 タグ

SGML でのコマンドはタグと呼ばれます。タグには開始タグと終了タ グがあり、開始タグは <タグ名> であり、終了タグは </タグ名> です。また、開始タグしか必要としないものもあり ますし、<タグ名/内容/ という短縮形式もあります。

開始タグと終了タグではさまれている部分に、そのタグの内容が適用されます。 LaTeX の環境と同じようなものですね。

3.3 原稿の書き方

ドキュメントつまり原稿は、いづれかのスタイルを指定しなければなりません。 スタイルには以下のものが指定できます。ほとんど、LaTeX で使われているも のと同様です。

article

もっともポピュラーなスタイルです。HOWTO にはこれを使いま す。

report

レポート形式です。

book

本の形式です。

manpage

man ページの形式です。

例えば article を使う場合には、

<!doctype linuxdoc system>

<article>

本文

</article>

なお、man ページについては、後で詳しく説明します。

3.4 タイトル

文書のタイトル、著者、日付や概要は、スタイル (例えば<article>) の後に記述します。

<title>

文書のタイトルを記述します。(必須)

<auther>

著者を記述します。(必須)

<trans>

翻訳者を記述します。(オプション)

<date>

文書のバージョンや日付を記述します。(オプション)

<tdate>

翻訳された文書のバージョンや日付を記述します。(オプション)

<abstract>...</abstract>

概要を記述します。(オプ ション)

例えば、以下のようになります。

<title>SGML を書こう！！
<author>さとけん＠ＦｏｒＵｓ,<tt/ken@gamba.forus.or.jp/
<date>v0.1 alpha, 20 September 1994
<abstract>
SGML を使って文書を書いてみよう。
</abstract>

【注意】 <date> は、<author> もしくは <trans> の 直後でないと、エラーとなります。

3.5 文章構成

文章の構成で、章や節を表すものとして、次のようなセクションタグが用意さ れています。これらは、タイトルの後に記述することができます。

<sect>

トップレベルの章で、LaTeX の section に相当します。 (1, 2, ...)

<sect1>

第 2 レベルの章で、LaTeX の subsection に相当します。 (1.1, 1.2, ...)

<sect2>

第 3 レベルの章で、LaTeX の subsubsection に相当し ます。(1.1.1, 1.1.2, ...)

<sect3>

第 4 レベルの章で、LaTeX の paragraph に相当します。

<sect4>

第 5 レベルの章で、LaTeX の subparagraph に相当しま す。

また、それぞれのタグの直後に、対応した見出しを記述します。

例えば文書の最初に``概要''という章を記述するには、

<sect>概要

<sect1>文章構成

セクションタグの後で、実際の本文を書くには <p> タグを本文の前に 記述して下さい。

例えば、次のようになります。

<sect>概要
<p>
この文書は、<tt/jlinuxdoc-sgml/ 文書整形システムの...

これは、sgmls パーサーに章見出しと本文の区切りを教えているのです。 しかし、段落の区切りを指定する必要があるのは、セクションタグの後だけで、 その後の段落の区切りは空行で大丈夫です。(こういう段落の区切り方は、 LaTeX でよくやられていることでしょう。)

例えば、次のようになります。

<p>
ここは最初の段落です。

ここは次の段落です。

ただ、最初の段落以外で <p> タグを使ってはいけないわけではありま せん。最初の段落で必ず指定しなければならないだけです。

3.6 文の整形と改行

jlinuxdoc-sgml では roff、LaTeX、HTML を使って、文 書を整形しますので、文字列や行を自動的に詰めたり、改行したりします。 よって、整形ルールはそれぞれのフォーマッタに依存します。

また、通常 SGML のソース文書での改行は無視されます。強制的に改行を行なう 場合は<newline> を行末に挿入してください。また、空行か <p> を挿入するとその前の文に改行が入り行間が空きます。

また、空白文字の扱いはフォーマッタによって異なります。プレーンテキスト の場合は空白文字をそのまま空白として出力しますが、DVI や PS, HTML では つめて出力(表示)されます。

変換前：

雨が降る降る
雨が降る
<p>
遊びに行きたし<newline>
傘はなし

草履の    鼻緒も
擦り切れた

変換後：

雨が降る降る 雨が降る

遊びに行きたし
傘はなし

草履の 鼻緒も 擦り切れた

タイトルページでは、改行は可能ですが空行を作ることはできません。従って <abstract> タグの中で空行を設けたり <p> を挿入してもエラー になるか無視されます。

なお、roff の整形はあまり精錬されていないため、他の環境でも空行が無視され たり、逆に空行が多すぎたりすることがあります。そのため、sgml2txt では 3 行以上の空行を 2 行の空行に縮めています。

3.7 コメント

SGML 文書のなかに、フォーマット出力には含めないコメントを書くには、

<!--
コメント
-->

3.8 打ち込んだ通りに出力する

LaTeX の verbatim 環境と同じように、打ち込んだ通りに出力させるには、 <verb>...</verb> で囲みます。

例えば、

ここは、<verb> と </verb> でかこまれています。

<verb>
ここは、<verb> と &etago;verb> でかこまれています。
</verb>

ただし、<verb>...</verb> の中でも、&,</ の 2 文字は 使えませんので、それぞれ、

• アンパサンド (&) を使うには &ero;
• 左ブラケット＋スラッシュ (</) を使うには &etago;

と入力します。

また、LaTeX の verbatim 環境を使う関係で、\end{verbatim} は記述し ないで下さい。

3.9 プログラムやアルゴリズム

プログラムやアルゴリズムをフォーマットするには、基本的には verb 環境を 用いますが、ちょっとアクセントをつける方法を説明します。

プログラムやアルゴリズムの出力には、

<code>...</code>

コード環境

<tscreen>...</tscreen>

スクリーン環境

<quote>...</quote>

クオート環境

コード環境

<code>...</code> ではさまれた部分をコード環境といいます。 コード環境は、ほとんど verb 環境と同じですが、上下に線が引かれます。

例えば、

これは <code>...</code> の例です。

<code>
これは <code>...&etago;code> の例です。
</code>

スクリーン環境

<tscreen>...<tscreen> ではさまれた部分をスクリーン環境とい います。スクリーン環境では、自動的にインデント、タイプライタ書体の指定 が行われます。主に verb 環境といっしょに使われます。

例えば、

これは <tscreen><verb>...</verb></tscreen> の例です。

<tscreen><verb>
これは <tscreen><verb>...&etago;verb>&etago;tscreen> の例です。
</verb></tscreen>

クオート環境

<quote>...<quote> ではさまれた部分をクオート環境といいます。 クオート環境では、自動的にインデントが行われます。

例えば、

これは <quote>...</quote> の例です。

<quote>
これは <quote>...&etago;quote> の例です。
</quote>

3.10 フォント

jlinuxdoc-sgml では LaTeX と同じようなフォントの指定をサポートし ています。ただし、プレーンテキストにする場合にはフォントの指定は無視さ れます。

em

強調 (例:em)

it

イタリック (例:it)

bf

ボールドフェース (例:bf)

sf

サン・セリフ (例:sf)

sl

スランテッド (例:sl)

tt

タイプライタ (例:tt)

cparam

cparam (例:cparam) #LaTeX の \cparam{} に相当します。

フォントを指定する場合には、指定する内容をタグではさみます。 例えば、タイプライタ書体にするには、以下のようにします。

Here is some <tt>typewriter text</tt> to be included in the document.

また、内容に``/''が含まれない場合には、以下の短縮形式を使う事もできま す。

Here is some <tt/typewriter text/ to be included in the document.

ただし、全ての出力形式 (HTML 等) でサポートされているわけではないので、 bf、it、tt 以外のフォントはあまり使うべきでは無いでしょう。bf、it、tt だけでも、文書を書くには十分でしょう。

3.11 箇条書き

jlinuxdoc-sgml ではいくつかの箇条書き (リスト) をサポートしていま す。サポートしているのは、以下の 3 種類の箇条書きです。

<itemize>...</itemize>

頭に記号を付けた箇条書き です。

<enum>...</enum>

項目に番号を付けた箇条書きです。

<descrip>...</descrip>

見出しを付けた箇条書きで す。

itemize リスト

itemize リストでは、それぞれの項目の頭に記号が付けられます。 例えば、

jlinuxdoc-sgml には

• itemize リスト
• enum リスト
• descrip リスト

があります。

<tt/jlinuxdoc-sgml/ には
<itemize>
<item>itemize リスト
<item>enum リスト
<item>descrip リスト
</itemize>
があります。

当然、ネスト (入れ子) も可能です。

enum リスト

enum リストでは、それぞれの項目に番号が付けられます。 例えば、

jlinuxdoc-sgml には

1. itemize リスト
2. enum リスト
3. descrip リスト

があります。

<tt/jlinuxdoc-sgml/ には
<enum>
<item>itemize リスト
<item>enum リスト
<item>descrip リスト
</enum>
があります。

当然、ネスト (入れ子) も可能です。

descrip リスト

descrip リストでは、それぞれの項目に見出しが付けられます。 例えば、

jlinuxdoc-sgml でサポートされている箇条書きの種類は

itemize

頭に・などの記号を付けた箇条書きです。

enum

項目に番号を付けた箇条書きです。

descrip

見出しを付けた箇条書きです。

の3種類です。

<tt/jlinuxdoc-sgml/ でサポートされている箇条書きの種類は
<descrip>
<tag/itemize/頭に・などの記号を付けた箇条書きです。
<tag/enum/項目に番号を付けた箇条書きです。
<tag/descrip/見出しを付けた箇条書きです。
</descrip>
の3種類です。

ただし、LaTeX を使う場合、見出しの部分には、 &bsol; が入力できませんので、注意して下さい。

当然、ネスト (入れ子) も可能です。

3.12 相互参照

<sect?> には自動的に通し番号が付けられますが、これを別の部分から 参照する方法を説明します。

まず、参照される部分へのラベル付けを行います。

<sect1>概要<label id="sec-intro">

これで、ラベルが付けられましたので、他の場所で以下のように参照すること ができるようになります。

概要については、<ref id="sec-intro" name="概要">を参照して下さい。

この場合、ref タグによって、sec-intro のセクション番 号に置き換えられます。

また、name は HTML や nroff に変換する場合 に必要です。

なお、HTML に変換した場合には、名前の部分をクリックすることに よって、その場所に移動できます。

例えば、この章は 相互参照です。

【裏技】

せっかくの相互参照も、節や章しか参照できないのではちょっと 機能不足ですね。実は、label は任意の場所に設定することができるのです が、LaTeX での参照の際に節番号を参照するので、節や章しか参照できない ようになっているのです。 だからといってあきらめる必要はありません。<htmlurl> というタグ を使って解決することができます。

次の節の htmlurlのタグ を参照のこと。

3.13 HTML での URL を記述するには

W3 (World Wide Web) で使われる URL (Universal Resource Locators) も記述することができます。

Mosaic 等で``Linux Documentation Projectのホームページ''と書かれている 部分をクリックすることで、sunsite.unc.edu の /mdw/linux.html ファイルを参照するようにするには以下のように します。

<url url="http://sunsite.unc.edu/mdw/linux.html" 
     name="Linux Documentation Projectのホームページ">

url の引数には、実際の URL を記述します。また name の引数には URL の名前や内容を記述しますが、これはオプションですので記 述しなくても結構です。

また、jf.gee.kyoto-u.ac.jp の /pub/JF/misc/linuxdoc-sgml-1.5.tar.gz を ftp して来る ようにするには、

<url url=
"ftp://jf.gee.kyoto-u.ac.jp/pub/JF/misc/linuxdoc-sgml-1.5.tar.gz">

例えば、 【オリジナルのLinuxdoc-SGML v1.5を入手するにはここをクリッ クして下さい。】 となります。

さらに、より機能の高い HTML の URL を表記するためには <htmlurl url=.... > というタグを使います。例えば、メールを送る ためのアドレスを書くときには、

<htmlurl url="mailto:ono@jf.gee.kyoto-u.ac.jp"
           name="ono@jf.gee.kyoto-u.ac.jp">

例：

ご用命の際は ono@jf.gee.kyoto-u.ac.jp まで。

<htmlurl> タグを使えば以下のようにして、同一文書中のラベルを直接 指定することもできます。

<htmlurl url="#CrossRef" name="相互参照の節"> を参照のこと。

相互参照の節 を参照のこと。

3.14 目次

目次を作るのは簡単です。目次をいれたい部分に

<toc>

ただし、実際に目次が挿入されるのは、LaTeX を通して作られる dvi と PS ファイルのみです。 textファイルでは単に無視されるだけですし、htmlファイ ルでは指定しなくても、作成されます。

3.15 横線を引くには

文書中で

<hrule>

3.16 FAQ を記述するには

ここでは、Linux コミュニティで利用されている FAQフォー マットを記述する方法を説明します。

たとえば、

[Item] ソフト名やハードウェアや規格・言語などのキーワード

[投稿者] 発言者の名前とメールアドレス

[日付] 発言した日付

[質問]

質問の詳細

[回答]

質問に対する回答

[投稿者] 発言者の名前とメールアドレス

[コメント]

質問あるいは回答に対するコメント(回答に自身がない場合など)

<faq>
<keyword>ソフト名やハードウェアや規格・言語などのキーワード
<poster>発言者の名前とメールアドレス
<pdate>発言した日付
<question>
質問の詳細
</question>
<answer>
質問に対する回答
</answer>
<poster>発言者の名前とメールアドレス
<coment>
質問あるいは回答に対するコメント(回答に自身がない場合など)
</coment>
</faq>

【注意】本来の FAQ フォーマットとの違いは、以下の通りです。

<FAQ> → <faq>
<Item> → <keyword>
<Subject> → <faq> の前に <sect?> として記述
<Poster> → <poster>
<Date> → <pdate>
<Q> → <question>
</Q> → </question>
<A> → <answer>
</A> → </answer>
<C> → <coment>
</C> → </coment>
</FAQ> → </faq>

FAQ をまとめた、 faqdb 形式のファイルを、jlinuxdoc-sgml で処 理できるファイルに変換するためのフィルタとして、bin/faqdb2doc がありますので、御利用下さい。このフィルタを使えば、上記の違いも変更さ れます。