<!-- $Id: sgmlmemo.sgml,v 1.8 2000/07/25 01:17:23 takes Exp $ -->

<!doctype linuxdoc system>
<article>
<title>SGML メモ (SGML 事始)
<author>佐野武俊 / <tt/Taketoshi Sano/, (<tt/kgh12351@nifty.ne.jp/) 
<date>$Date: 2000/07/25 01:17:23 $
<abstract>
この文書は初めて SGML を使って文書を作成してみた経験をもとに、
これから SGML での文章作成を始めようとしている人を対象に、
少しでも参考になればと思って書いたものです。

SGML (LinuxDoc DTD) を使って文書を作成すると、jLinuxDoc-SGML という
変換ツールを利用することで簡単に HTML, TeX (DVI), Text などへ
変換できます。SGML は現在 JF / LDP などでも使われており、
Linux 関係の HOWTO 文書における標準フォーマットといって良いでしょう。

</abstract>

<toc>

<sect>はじめに
<p>
この文書は 
<url url="http://metalab.unc.edu/LDP/" name="LDP (Linux Documentation Project)">
や
<url url="http://www.linux.or.jp/JF/" name="JF (Japanese FAQ) Project">
などで以前使われていた Linuxdoc-SGML および
その日本語化版 jLinuxdoc-SGML をベースにしています。
<p>
現在 LDP では linuxdoc-SGML を継承・発展させた SGML-Tools を
標準の変換ツールとして利用しているようです。
<p>
これを受けて JF でも現在 SGML-Tools 1.09 への日本語化パッチが
用意されており、SGML-Tools 1.09j として利用されています。
<p>
(2000 6/30 追加: SGMLTools の開発者である Cees de Groot が 
SGMLTools (v2) の開発を打ち切り、SGMLtool-Lite に移行したのを
受け、LinuxDoc DTD 専用ツールとして linuxdoc-tools の開発を
スタートしました。今後は sgml-tools 用のパッチの開発ではなく
linuxdoc-tools の開発を進めていきます。)
<p>
これらについては <url url="http://www.linux.or.jp/JF/" name="JF Project">
によって配布されている <url url="http://www.linux.or.jp/JF/JFdocs/sgmlnote.html"
 name="SGML Tips for JF"> を参照してください。
<p>

<sect>基本型 (全体の枠組)
<p>

<sect1>doctype, article
<p>
実は SGML というのは非常に柔軟な道具であって、
<quote>
 <tt/Document Type Definition ``DTD''/
</quote>
(日本語訳は「文書型定義」だそうです) というテンプレートの
ようなものを作成することで、いろんな書式に対応できます。
<p>
が、ここでは「 LTGP 向けの文書を作成する」という目的がありますから、
<tt/JF (Japanese FAQ Project)/ で開発された <tt/jLinuxdoc-SGML/ と
いう型式に従って書きます。
<p>
この場合、最初の行に

<quote>
&lt;!doctype linuxdoc system&gt;
</quote>

と書き、次の行に

<quote>
&lt;article&gt;
</quote>

さらに最後の行に

<quote>
&etago;article&gt;
</quote>

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

<quote>
<verb>
&lt;!doctype linuxdoc system&gt;
&lt;article&gt;
(本文)
&etago;article&gt;
</verb>
</quote>

です。
<p>

<sect1>title,author,date,abstract,toc,sect,p
<p>
最初に書いた doctype, article などは本文の外にある「大枠」ですが、
本文の中にも「必ず書いておくべき項目」というものがあります。
この項のタイトルになっている項目がそれで、以下のような意味があります。

<itemize>
<item> title : タイトル、題名 (そのままですね)
<item> author : 作者、著者、書いた人。後々のために
メールアドレスも併記しておくと良いでしょう。
<item> date : 作成した日付。バージョン番号をここに書いても良いです。
<item> abstract : 要約。内容をまとめたもの。
<item> toc : Table Of Contents, つまり目次のこと。自動で作成されます。
<item> sect : Section, つまり節。これを基準にして目次が作成されます。
<item> p : Paragraph, 段落だそうです。 (thanks to Takashiro san :)
これを指定すると、あとでテキストに変換した場合、その位置で一行あけて
段落わけされます。
また各節の中で本文を書き始める前には、必ずこれを指定します。
</itemize>

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

<quote>
<verb>
&lt;title&gt; テスト文書 (test article)
&lt;author&gt; わたし &lt;newline&gt;
&lt;date&gt; ver 0.1, テスト版
&lt;abstract&gt;
ここには要約 (アブストラクト、サマリー) を書きます。
&etago;abstract&gt;
&lt;toc&gt;
&lt;sect&gt;最初の節
&lt;p&gt;
</verb>
節の中で本文を書くには、上のようにまず &lt;sect&gt; に
続けて &lt;p&gt; を書いて、その下から始めます。
<p>
ちなみに &lt;sect&gt; の上にある &lt;toc&gt; は
「ここに目次を作って置いといてね」という意味で、
後でコマンドを使ってテキストや HTML に変換する時に
自動的に目次が作成されます。これは結構便利な機能です。
</quote>

雰囲気はつかめたでしょうか ? あとは必要に応じて
&lt;sect&gt; や &lt;p&gt; を追加していけば、どんどんと
長い文章を書いていける、というものです。
<p>

<sect>使える文字、使えない文字
<p>
さてここで ``SGML'' で文章を書くときに気をつけなければ
いけないことがひとつあります。
<p>
それは、 ``SGML'' で書く文章には「使える文字」と「使えない文字」が
あるということです。ついでに書いておくと日本語コードは EUC を使うことに
決まっています。また行頭に . (ピリオド) や ' (アポストロフィ) が
きてしまうと後で変換に使用するコマンドがうまく動作しなくなり、
きちんと出力できなくなるので、これらも避けましょう。
<p>

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

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

これらについては、本文中でなら普通に使ってしまって構いません。
ただし、 &lt;author&gt; のところでメールアドレスを書くために @ を
そのまま使うとエラーになる場合があるみたいです。 (私はなりました。) 
<p>
この場合はメールアドレスを &lt;tt/user@domain/ のように
 &lt;tt/ と / で囲むと良いようです。お試し下さい。
<p>

<sect1>使えない文字
<p>
以下の文字は、 SGML のコマンドとして解釈されてしまうので、それぞれ
右に示すように書いて下さい。テキストや HTML へ変換する時に意図した
文字に置き換えられます。

<itemize>
<item>チルダ &dquot;&tilde;&dquot; (<tt>&tilde;</tt>)  → <tt>&amp;tilde;</tt>
<item>左角かっこ (<tt>&lsqb;</tt>) → <tt>&amp;lsqb;</tt>
<item>右角かっこ (<tt>&rsqb;</tt>) → <tt>&amp;rsqb;</tt>
<item>アンパサンド (<tt>&amp;</tt>) → <tt>&amp;amp;</tt>
<item>左ブラケット (<tt>&lt;</tt>) → <tt>&amp;lt;</tt>
<item>右ブラケット (<tt>&gt;</tt>) → <tt>&amp;gt;</tt>
<item>左ブラケット＋スラッシュ (<tt>&etago;</tt>) → <tt>&amp;etago;</tt>
<item>ドルマーク (<tt>&dollar;</tt>) → <tt>&amp;dollar;</tt>
<item>シャープ (<tt>&num;</tt>) → <tt>&amp;num;</tt>
<item>パーセント (<tt>&percnt;</tt>) → <tt>&amp;percnt;</tt>
<item>バックスラッシュ (<tt>&bsol;</tt>) → <tt>&amp;bsol;</tt>
<item>二重引用符 → <tt>``</tt> と <tt>''</tt> 
( <tt>&dquot;</tt> を表示させるには <tt>&amp;dquot;</tt> )
</itemize>

「わかった」と思っても、最初は意外と見落し易いものです。
<p>
もしチェックコマンド (sgmlcheck) でエラーになったら、ログの出力を
リダイレクトして、ちゃんと見直しましょう。
<p>
それから、上記の右にある表記ですが、 ``;'' も
その一部です。 ``&amp;lt'' とだけ書いて「エラーになった」
と騒がないようにしましょう (経験者は語る)。
<p>

<sect>修飾 (タグ)
<p>
さて、今までの部分だけで、とりあえずいくつかの節に分けて構成された
文章に、題名、作者、日付などの必要なヘッダーと目次を付けて ``SGML'' で
書けるようになったと思います。
<p>
この節は、もうちょっと文章表現に凝りたい、という人のための
使って便利なタグの紹介です。
<p>
「タグ」とは、今までに出てきた &lt;sect&gt; や &lt;p&gt;
それに &lt;title&gt; などや &lt;!doctype linuxdoc system&gt; 
なども含めた、
&lt; と &gt; で囲まれた「項目指定」のことです。
<p>
例えば、以下のようなタグを覚えておくと便利でしょう。
<p>

<sect1>&lt;sect1&gt;
<p>
&lt;sect&gt; の下をさらに分割する際に使います。
「節 (セクション)」の下の「小節 (サブセクション)」に
相当するものです。
<p>
ちなみに、 &lt;sect&gt; から &lt;sect4&gt; まで 5 段階の分割レベルが
用意されています。本文の前に &lt;p&gt; が必要なのはどの分割レベルでも
同じです。
<p>

<sect1>&lt;newline&gt;
<p>
強制的に改行させる場合に使います。使い過ぎに注意しましょう。
<p>
この文書は最初の頃、「使い過ぎに注意」と書いておきながら実は
たくさん使っているという「悪い見本」になっていました。
<p>
文書の出来上がりを html に変換して kterm + lynx で確認したり、
text に変換して kterm + less で確認したりしていたのですが、
その環境で改行が単語の途中に挿入されたりすると妙に気になって
「外観」をコントロールしようとたくさん並べていたのです。
<p>
しかし、例えば Netscape Navigator でウィンドウサイズを 2, 3 度
変更しながら眺めていると、「改行にこだわる」のは無意味だな、と
いうことが実感できました。
<p>
以上のような経過をたどって、この文書では途中から &lt;newline&gt; を
大幅にカットし、ほとんど使わないように心がけています。
<p>

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

<itemize>
<item>アンパサンド (<tt>&amp;</tt>) → <tt>&amp;ero;</tt>
<item>左ブラケット＋スラッシュ (<tt>&etago;</tt>) → <tt>&amp;etago;</tt>
</itemize>

を使って下さい。
<p>

<sect1>&lt;itemize&gt; と &etago;itemize&gt;
<p>
箇条書きで使います。

例えば
<tscreen>
<tt/SGML (jlinuxdoc-sgml)/ での箇条書きは
<itemize>
<item>項目 1
<item>項目 2
<item>項目 3
</itemize>
こんな風になります。
</tscreen>
と出力したい場合は
<tscreen><verb>
&lt;tt/SGML (jlinuxdoc-sgml)/ での箇条書きは
&lt;itemize&gt;
&lt;item&gt;項目 1
&lt;item&gt;項目 2
&lt;item&gt;項目 3
&etago;itemize&gt;
こんな風になります。
</verb></tscreen>
のように、リストの先頭に <tt>&lt;itemize&gt;</tt> を置き、
それぞれの項目の先頭に <tt>&lt;item&gt;</tt> を付けて、
最後に <tt>&lt;/itemize&gt;</tt> で締めます。
<p>

<sect1>&lt;url ... &gt;
<p>
HTML に変換した時に、選択すると他の場所の URL へ
ジャンプできるようにするためのタグです。
<p>
Web ブラウザで &dquot;JF (Japanese FAQ Project)&dquot; と表示されている
部分を選択して、 <tt>&lt;http://www.linux.or.jp/JF/&gt;</tt> へ
ジャンプできるようにするには

<tscreen>
<verb>
&lt;url url="http://www.linux.or.jp/JF/" 
     name="JF (Japanese FAQ Project)"&gt;
</verb>
</tscreen>

という風に書きます。
<p>
<tt>url</tt> の引数には、実際の URL を書きます。
また <tt>name</tt> の引数にはURL の名前や内容を書きます。
これはオプションなので、書かなくても問題無いです。
<p>

<sect>コマンド
<p>
私は最初解説書 (jguide.txt) の「 sgmls がパーサー」
という部分だけ読んで、もろに ``sgmls sample.sgml'' を実行してしまい、
「おかしい。動かんぞ！どうなっているんだ。」などと騒いてしまいました。
<p>
実はあとでちゃんと読めば

<itemize>
<item> 文法チェックは sgmlcheck
<item> テキストへの変換は sgml2txt
<item> HTML への変換は sgml2html
</itemize>

ということが書いてあったのです。
<p>
こんな失敗をする奴がそうそういるわけも無いでしょうが、
一応、「このコマンドだけ覚えておけば大丈夫でしょう」と
いうわけで、この節を書いておきます。
<p>
いいですね ?  sgmlcheck/sgml2txt/sgml2html ですよ ?
覚えましたか ? (クドイって、、、)
<p>
ちなみに使い方は ``sgmlcheck anatano.sgml'' のように
コマンド名のあとスペースを入れて SGML のファイル名を
指定します。
<p>

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

<sect1>Debian GNU/Linux
<p>
パッケージ： main/text/linuxdoc-sgml-ja
<p>
Debian JP プロジェクトによってリリースされた追加パッケージである
hamm-jp および slink-jp では ``linuxdoc-sgml-ja_1.5.1-5.deb'' が
バイナリパッケージのファイル名になります。
<p>

<sect1>Plamo Linux
<p>
パッケージ: contrib/Text/jlx-sgml.tgz
<p>

<sect1>Vine Linux
<p>
パッケージ: RPMS/jlinuxdoc-sgml-1.5-2.i386.rpm
<p>

<sect1>その他
<p> 
バイナリパッケージがあるかどうかわかりませんでした。
御存知の方は教えて下さい。
<p>
以前は JF の Web ページ
 <url url="http://www.linux.or.jp/JF/workshop/guidance-sgml.html"
   name="日本語化 SGML-Tools による文書作成"> 
から

<itemize>
<item> "linuxdoc-sgml-1.5.tar.gz" (Linuxdoc-SGML v1.5 のソースコード)
<item> "jlinuxdoc-sgml-1.5.diff.tgz" (上記のコードに対する日本語パッチ)
</itemize>

を入手できたのですが、現在は LDP が既に linux-doc-sgml を
継承・発展させた新しいバージョンである SGML-Tools に移行しており、
翻訳の都合もあって JF でも SGML-Tools とその日本語化パッチしか
配布していません。
<p>
もし ftp サイトなどに見つからなければ上記の Debian または Plamo の
配布サイトからソースアーカイブを入手することが可能です。
<p>
この SGML Memo は「初めて SGML を使う人」を対象にしているため、
現在各ディストリビューションに収録されている jLinuxDoc-SGML に
ついて主に説明しています。JF などでの作業のために SGML-Tools が
必要な場合には <url url="http://www.linux.or.jp/JF/JFdocs/sgmlnote.html"
 name="SGML Tips for JF"> を参照してください。
<p>

<sect>参考文献など
<p>

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

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

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

<sect1>便利なツール
<p>
JF の Web サイトにある
 <url url="http://www.linux.or.jp/JF/workshop/guidance-sgml.html"
   name="日本語化 SGML-Tools による文書作成"> 
というページには「SGML 文書作成を支援するツール」として
<url url="http://www.linux.or.jp/JF/workshop/archives/yasgml_1.5-5.tar.gz"
   name="yasgml.el">
が紹介されています。これ、私も最近多用していますが、非常に便利です。
まだ使ったことが無ければ、是非一度試してみることをお勧めします。
<p>
特にまだ SGML での文書作成に慣れていない人にとっては、
メニューから &lt;sect&gt; などの挿入を選択できる機能が
とてもありがたいです。
<p>
なお、Debian の開発版である potato には yasgml のパッケージが
含まれています。Debian ユーザーの方は、こちらをインストールすると
便利でしょう。 <p>

<sect>おわりに
<p>
<sect1>一緒に SGML で文書を作成してみませんか ?
<p>
これで「 SGML メモ」を終わります。え、簡単すぎるって ?
実は私もこれが SGML で書いた文章の第 2 弾です。
まことにすみませんが、これ以上高度なことはわかりません。
<p>
(実はその後いくつか SGML での文章作成を経験したので、
現在はこの文書を初めて作成した時よりも、すこしばかり
知識が増えたように思います。が、実はたいして変っていないかも。)
<p>
SGML の詳細については、既に充分親切に説明してある文献が世の中に
あります。この文書はあくまでも「最初の一歩」の手助けになることを
期待して書かれています。
<p>
もし、「この表現はもっとこうしたほうがわかりやすいよ」とか
「実は私はこんな失敗をしたんだけど、これも追加して書いておいて
くれないか」という要望があれば、遠慮なくメールで教えて下さい。
<p>
できれば LTGP の ML に参加して、あるいは JF ML に参加して、
それぞれ盛り上げてくれると、非常に嬉しいです。
<p>

<sect1>この文書ができたきっかけ
<p>
私が SGML による文書作成を始めたのは 1998 年の暮に DebianTips という
文書を公開してもらおうと LTGP (Linux Total Guide Project) の ML へ
参加したのがきっかけでした。
<p>
このメモはその経験から、これから SGML での文章作成を始めようと
している人を対象に、少しでも参考になればと思って書いたものです。
<p>
SGML (LinuxDoc DTD) での文書作成は、慣れてくれば全然難しいものでは
ありません。なにか思いついたことがあれば、是非一度 SGML を使って
文章を書いてみてください。きっと便利な道具になると思います。
<p>

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

<!--
$Log: sgmlmemo.sgml,v $
Revision 1.8  2000/07/25 01:17:23  takes
apply patch from SEI Hideki <seih@dig-it-all.net>. Thanks to him!

Revision 1.7  2000/06/30 09:39:53  takes
 * docs/sgmlnote/sgmlnote.sgml: update (jf.linux.or.jp ->
 * docs/sgmlmemo/sgmlmemo.sgml: www.linux.or.jp/JF/) based
   on kamo-san's advice. Thanks.

Revision 1.6  2000/06/30 02:35:51  takes
update for the recent linuxdoc-tools upload (the archive name is changed!)

Revision 1.5  2000/01/05 22:39:46  takes
add caution for apostrophe at the beggining of the line

Revision 1.4  1999/12/15 07:22:45  takes
debiantips.sgml: update sgml-tools and patches description
sgmlmemo.sgml, sgmlnote.sgml: update sgml-tools related,
and new URI for yasgml.el (yasgml.tar.gz)
workshop/guidance-sgml.m4: update URI for yasgml.el

Revision 1.3  1999/11/28 16:22:11  takei

* docs/sgmlmemo/sgmlmemo.sgml: [JF:09402] を反映.

Revision 1.2  1999/11/25 04:04:42  takes
update to reflect comment from takei-san

Revision 1.1  1999/11/11 04:12:19  takes
documents from ltgp. initial draft :)

Revision 1.1  1999/11/10 22:02:37  sano
Initial revision

Revision 1.2  1999/08/20 14:42:05  sano
update to cordinate with SGML Note

Revision 1.4  1999/05/25 19:00:12  sano
add Vine Linux's package of jlinuxdoc-sgml

Revision 1.3  1999/05/24 12:05:53  sano
add description about debian package of yasgml.el

-->
