From c1da92fd79906f4fa4e0d8e128ec5449dc36210e Mon Sep 17 00:00:00 2001 From: fukachan Date: Wed, 9 May 2001 09:37:35 +0000 Subject: move docbook.sgml to devel/ add more on what is docbook, tools and pointers --- fml/doc/ja/tutorial/devel/docbook.sgml | 550 +++++++++++++++++++++++++++++++ fml/doc/ja/tutorial/docbook.sgml | 391 ---------------------- fml/doc/ja/tutorial/include/chapters.ent | 6 +- 3 files changed, 552 insertions(+), 395 deletions(-) create mode 100644 fml/doc/ja/tutorial/devel/docbook.sgml delete mode 100644 fml/doc/ja/tutorial/docbook.sgml (limited to 'fml/doc') diff --git a/fml/doc/ja/tutorial/devel/docbook.sgml b/fml/doc/ja/tutorial/devel/docbook.sgml new file mode 100644 index 00000000..3528df49 --- /dev/null +++ b/fml/doc/ja/tutorial/devel/docbook.sgml @@ -0,0 +1,550 @@ + + + + + + SGML の書き方 + + +fml-devel (fml 5.0) のドキュメントでは、SGML の DTD は + + + DOCBOOK + + +をごくごく普通に使うことにします。 + + + +ここでは、SGML を書くために最小限必要な知識についてメモします。 + + + +基本的な SGML の書式は、当たり前 + + + HTML は SGML 形式の応用の(最も有名な)一例です。 + そのため本質的なシンタックスは HTML と同じということになります。 + + +ですが、正しい HTML の書き方と同様です。 +本 Appendix で、２、３の典型的な SGML テンプレートをメモしておくので、 +それらを適当に切り剥ぎしていけばなんとかなるはずです。 + + + + + + + SGML の概念 + + + +SGML は本や短い文書(記事)を作成するに使います。 +本や記事の論理構造を記述するための規格です。 +HTML のもっと厳密なものだと思って下さい + + + 正確には HTML が SGML の一部です。 + HTML の方がはるかに有名になってしまったので、 + 「HTML のもっと厳密なもの…」といった説明が良くされます :) + + + + + +例えば、”本”という概念を考えてみます。 +まず”本”には章、節といった構成単位があります。 +節の中にはパラグラフがありますし、文には脚注がついたり、 +図などが挟み込まれたりします。 + + + +これらの概念には、ある関係があります。 +例えば”章”は”節”を含みますが、”節”は”章”を含みません。 +そして、文は必ずあるパラグラフの中にあるものです。 + + + +そういった概念をどう表現するべきか？を規定したものが DTD (Data Type +Definition)といえます。 +DTD は自由に定義すれば良いのですが、かなり大変です。 +誰かが作った DTD コレクションが世の中にはあるので、それを +使うのが便利です。 +我々は DTD として docbook というものを使う + + + 我々が DOCBOOK を選んだ理由は簡単で、 + 多くの場所で使われているからです。 + ということは、docbook のタグを書ける人は世の中に多いという意味です。 + + +ことにしています。 + + + +DOCBOOK は OASIS-0PEN.ORG が保守している DTD 集です。 +非常に有名なもので、デファクトスタンダードといってもよいでしょう。 +リファレンスですが、オライリーから本も出ていますし、 +(わかりやすいかどうかは別として;) +ドキュメントも豊富です。 +Free の UNIX などをはじめ、多くのプロジェクトで使われています。 + + + +つまり +SGML を使うことで得られる最大の意義は「ある基準となるもの」に +規格化ないしは強制されるということです。 +これは SGML の構文による規制という意味ではありません。 +ある概念に従うことに強制されようということです。 + + + +ここで”概念”といっているのであって、”見栄え”については +降れていないことに注意して下さい。 +HTML では概念と見栄えは(むしろ意識的に)はっきり分離していないといえま +す。 + + + +見栄えは DTD とは別の何かで定義されます。 +通常スタイルシートというものです。 +HTML 4.0 などでご存知の CSS と同じ概念です。 + + + +スタイルシートの記述をするプログラミング言語が必要です。 +docbook では schema (lisp の一種) ベースの +DSSSL (Document Style Semantics and Specification Language) +を使います。 + + + + +また SGML では論理構造しか記述しないので見栄えはコンバータ次第で +どうとでもなります。 +HTML、テキスト、ROFF、PS、PDF、RTF を始め、 +いろいろなものへ変換するやり方が用意されています。 + + + + + + + + + + 本( book )形式のテンプレート + + +docbook DTD には book や article といった代表的な形式についての +定義があります。 + + + +book スタイルの典型的な SGML のテンプレートは次のようになります。 + + +<!doctype book public "-//OASIS//DTD DocBook V3.1//EN" [ + <!entity % include SYSTEM "include.sgml"> %include; +]> +<book> + + &bookinfo; + &preface; + + <toc></toc> + + <part> + <title> タイトル </title> + <partintro> + <para> + 本パートは…目指しています。 + </para> + </partintro> + + <!-- 以下、各章が並ぶ --> + &overview; + </part> +</book> + + + + +part や title は文字通りの意味です。 + + + +ここで注目するべきは、SYSTEM というキーワードのある、 +2 行目です。 +これは include.sgml を include する命令です。 +C 言語の #include や +perl の require() と同様の働きをしています。 + + + +さらに、 include.sgml の中では次のような命令が定義されています。 + + +<!-- include する SGML ファイル群 --> +<!entity bookinfo SYSTEM "bookinfo.sgml"> +<!entity overview SYSTEM "overview.sgml"> + + +これらの定義により +&bookinfo; +命令で +bookinfo.sgml +が include されるようになります。 + +このようにして、文書本体と +include するべき定義ファイルを +分離することができます。 + + + + + + + + HTML の <UL> 相当 + + +<itemizedlist> + + <listitem> + <para> + アイテム１ + </para> + </listitem> + + <listitem> + <para> + アイテム２ + </para> + </listitem> + +</itemizedlist> + + + +例えば + + +<itemizedlist> + + <listitem> + <para> + けんけんはきたきつね + </para> + </listitem> + + <listitem> + <para> + るどるどはテディベア + </para> + </listitem> + +</itemizedlist> + + +は次のようになります。 + + + + けんけんはきたきつね + + + るどるどはテディベア + + + +数字付のアイテムは orderedlist です。 + + + + けんけんはきたきつね + + + るどるどはテディベア + + + + + + + + + + + HTML の <TABLE> 相当 + + +<para> + <table> + <title> テーブルのタイトル </title> + <tgroup cols=2> + + <thead> + <row> + <entry> キー </entry> + <entry> 値 </entry> + </row> + </thead> + + <tbody> + <row> + <entry> キー 1 </entry> + <entry> 値 1 </entry> + </row> + + <row> + <entry> キー 2 </entry> + <entry> 値 2 </entry> + </row> + </tbody> + + </tgroup> + </table> +</para> + + + +例えば + + +<para> + <table> + <title> table description </title> + <tgroup cols=2> + + <thead> + <row> + <entry> 名前 </entry> + <entry> 説明 </entry> + </row> + </thead> + + <tbody> + <row> + <entry> けんけん </entry> + <entry> きたきつね </entry> + </row> + + <row> + <entry> るど </entry> + <entry> テディベア </entry> + </row> + </tbody> + + </tgroup> + </table> +</para> + + +は次のようになります。 + + + テーブルの見本 + + + + + 名前 + 説明 + + + + + + けんけん + きたきつね + + + + るど + テディベア + + + + +
+ + + + + + + + + ツール群 + + +SGML を HTML などに翻訳するために、いくつかのツールが必要です。 +DTD と DSL の規格文書群は必須です。 +おそらく openjade と opensp も必須のプログラムです。 +その他はオプショナルで、各自が好きにすればよいようです。 + + + +fml 5.0 では、以下のプログラムを使って HTML やテキストファイルを作成し +ています。 + + + + + openjade 1.3 + + + + + + opensp 1.3.4 + + + + + + SGMLtools-Lite 3.0.2 + + + + + +多くの OS では附属のパッケージシステムで一発ポン！てなもんでしょう。 + + + +なお +sgmltools がなくても SGML から HTML を作ることができます。 +どのツールを使うかは、あなたがどれを便利に思うか？次第です。 + + + +SGML からの変換には +fml/doc/share/sgml/ にある fml.dtd fml.dsl も使っています。 +これらは各 Makefile 内に +定義(jade に与えるオプション -c や -d オプション)が記述されています。 + + + + + +NetBSD 1.5-stable 系列(およびそれ以前のバージョン)上で +openjade を compile するには unproven-pthreads が必要ですが、 +以前作った時の変な include ファイルが残っていて +openjade をうまく compile できないことがありました。 + +うまくいかない時はまっさらにして全部やり直してみましょう。 + + + + + + + + + 例: SGML から HTML を作る + + + + +book.sgml + +から html ファイルを作るには sgmltools を次のように実行します。 + +% sgmltools -b html book.sgml + +正しく動けば、 +これだけで book/ ディレクトリの下に HTML ファイルが作成されるはずです。 + + + +もし、独自のカタログや DSSSL のファイルを指定する必要があれば + +% sgmltools -b html -j '-c /some/where/catalog -d /some/where/your.dsl' book.sgml + +などとします。 +-j +は openjade に与えるオプションを指定しています。 +-c +でカタログを指定しない場合、 +sgmltools は /etc/sgml/catalog ファイルを使います。 + + + + + + + + + 見栄えを変更する + + +SGML は論理的な構造を記述している言語です。 +HTML の各ページに URL をつけたいとか、画像をつけたいといった +”見栄えの記述”は直接はできません。 + + + +そこで、見栄えは DSL により記述をすることになります。 +しかしながら、DSL は本質的に LISP (List Processre) 言語なので、 +LISP を知らないとちょっと手が出ないでしょう。 + + + +見栄えは誰かが頑張った結果だけ使えということなのかもしれません。 + + + +ちなみに fml 5.0 の DSL の記述は + + + fml/doc/share/sgml/fml.dsl + + +にあります。 +こういったものを書かないと見栄えを変えることができません ;) + + + + + + + + その他の情報源 + + + +SGML の書き方については + + + FreeBSD の初心者向けチュートリアル + + +などを参照して下さい。 + + + +必要なツールのインストールについては + + http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/ + +を参照して下さい。 + + + +SGML のタグの一覧は + + + DOCBOOK definitive guide (O'reilly) + + +のオンライン版を参照すると良いでしょう。 + + + + + diff --git a/fml/doc/ja/tutorial/docbook.sgml b/fml/doc/ja/tutorial/docbook.sgml deleted file mode 100644 index 3c5e7460..00000000 --- a/fml/doc/ja/tutorial/docbook.sgml +++ /dev/null @@ -1,391 +0,0 @@ - - - - - - SGML の書き方 - - -fml-devel (fml 5.0) のドキュメントでは、SGML の DTD は - - - DOCBOOK - - -をごくごく普通に使うことにします。 - - - -ここでは、SGML を書くために最小限必要な知識についてメモします。 - - - -基本的な SGML の書式は、当たり前ですが、正しい HTML の書き方と同様です。 -本 Appendix で、２、３の典型的な SGML テンプレートをメモしておくので、 -それらを適当に切り剥ぎしていけばなんとかなるはずです。 - - - - - - - 本( book )形式のテンプレート - - -book スタイルの典型的な SGML のテンプレートは次のようになります。 - - - -<!doctype book public "-//OASIS//DTD DocBook V3.1//EN" [ - <!entity % include SYSTEM "include.sgml"> %include; -]> -<book> - - &bookinfo; - &preface; - - <toc></toc> - - <part> - <title> タイトル </title> - <partintro> - <para> - 本パートは…目指しています。 - </para> - </partintro> - - <!-- 以下、各章が並ぶ --> - &overview; - </part> -</book> - - - -part や title は文字通りの意味です。 - - - -ここで注目するべきは、SYSTEM というキーワードのある、 -2 行目です。 -これは include.sgml を include する命令です。 -C 言語の #include や -perl の require() と同様の働きをしています。 - - - -さらに、 include.sgml の中では次のような命令が定義されています。 - - -<!-- include する SGML ファイル群 --> -<!entity bookinfo SYSTEM "bookinfo.sgml"> -<!entity overview SYSTEM "overview.sgml"> - - -これらの定義により -&bookinfo; -命令で -bookinfo.sgml -が include されるようになります。 - -このようにして、文書本体と -include するべき定義ファイルを -分離することができます。 - - - - - - - - HTML の <UL> 相当 - - -<itemizedlist> - - <listitem> - <para> - アイテム１ - </para> - </listitem> - - <listitem> - <para> - アイテム２ - </para> - </listitem> - -</itemizedlist> - - - -例えば - - -<itemizedlist> - - <listitem> - <para> - けんけんはきたきつね - </para> - </listitem> - - <listitem> - <para> - るどるどはテディベア - </para> - </listitem> - -</itemizedlist> - - -は次のようになります。 - - - - けんけんはきたきつね - - - るどるどはテディベア - - - -数字付のアイテムは orderedlist です。 - - - - けんけんはきたきつね - - - るどるどはテディベア - - - - - - - - - - - HTML の <TABLE> 相当 - - -<para> - <table> - <title> テーブルのタイトル </title> - <tgroup cols=2> - - <thead> - <row> - <entry> キー </entry> - <entry> 値 </entry> - </row> - </thead> - - <tbody> - <row> - <entry> キー 1 </entry> - <entry> 値 1 </entry> - </row> - - <row> - <entry> キー 2 </entry> - <entry> 値 2 </entry> - </row> - </tbody> - - </tgroup> - </table> -</para> - - - -例えば - - -<para> - <table> - <title> table description </title> - <tgroup cols=2> - - <thead> - <row> - <entry> 名前 </entry> - <entry> 説明 </entry> - </row> - </thead> - - <tbody> - <row> - <entry> けんけん </entry> - <entry> きたきつね </entry> - </row> - - <row> - <entry> るど </entry> - <entry> テディベア </entry> - </row> - </tbody> - - </tgroup> - </table> -</para> - - -は次のようになります。 - - - テーブルの見本 - - - - - 名前 - 説明 - - - - - - けんけん - きたきつね - - - - るど - テディベア - - - - -
- - - - - - - - - ツール群 - - - -SGML を HTML などに翻訳するために、いくつかのツールが必要です。 -僕は、これらのプログラムを使っています。 - - - - - openjade 1.3 - - - - - - opensp 1.3.4 - - - - - - SGMLtools-Lite 3.0.2 - - - - - -多くの OS では附属のパッケージシステムで一発ポン！てなもんでしょう。 - - - -適宜、これらのプログラムをインストール後、 -fml/doc/share/sgml/catalog.sample -を参考にして -/etc/sgml/catalog を編集する必要があるかも知れません。 - - - - -SGML からの変換には -fml/doc/share/sgml/ にある fml.dtd fml.dsl も使っています。 -これらは各 Makefile 内に -定義(jade に与えるオプション -c や -d オプション)が記述されています。 - - - - - -NetBSD 1.5-stable 系列(およびそれ以前のバージョン)上で -openjade を compile するには unproven-pthreads が必要ですが、 -以前作った時の変な include ファイルが残っていて -openjade をうまく compile できないことがありました。 - -うまくいかない時はまっさらにして全部やり直してみましょう。 - - - - - - - - - 見栄えを変更する - - -SGML は論理的な構造を記述している言語です。 -HTML の各ページに URL をつけたいとか、画像をつけたいといった -”見栄えの記述”は直接はできません。 - - - -そこで、見栄えは DSL により記述をすることになります。 -しかしながら、DSL は本質的に LISP (List Processre) 言語なので、 -LISP を知らないとちょっと手が出ないでしょう。 - - - -見栄えは誰かが頑張った結果だけ使えということなのかもしれません。 - - - -ちなみに fml 5.0 の DSL の記述は - - - fml/doc/share/sgml/fml.dsl - - -にあります。 -こういったものを書かないと見栄えを変えることができません ;) - - - - - - - - その他の情報源 - - - -SGML の書き方については - - - FreeBSD の初心者向けチュートリアル - - -などを参照して下さい。 -SGML のタグの一覧は - - - DOCBOOK definitive guide (O'reilly) - - -のオンライン版を参照すると良いでしょう。 - - - - - diff --git a/fml/doc/ja/tutorial/include/chapters.ent b/fml/doc/ja/tutorial/include/chapters.ent index 1059fd3a..1db7237f 100644 --- a/fml/doc/ja/tutorial/include/chapters.ent +++ b/fml/doc/ja/tutorial/include/chapters.ent @@ -1,5 +1,5 @@ @@ -49,6 +49,7 @@ + @@ -60,7 +61,4 @@ - - - -- cgit v1.2.1