SmatDocは浅海 智晴さんが開発したXMLをベースにしたドキュメント生成ツールです。SmartDoc形式(XML)で書いたドキュメントを、HTML、LaTeX、JavaHelpに変換することができます。
SmartDocはJavaで書かれたプログラムなので、実行にあたってはSmartDocの他にJava実行環境が必要です。JavaはSun MicrosystemsのJavaサイトや各種雑誌・書籍付属CD-ROM等から入手してください。JavaWorld誌には大抵毎号載っています。
SmartDocのホームページからダウンロードします。2007年6月9日現在、正式版としてはバージョン1.1が最新です。ベータ版としては1.2b-20070604が公開されています。メンテナンスはバグフィックスを含めて1.2bで実施されているので、1.2bを使用するのがよいかもしれません。
http://www.smartdoc.jp/
インストール手順については上記サイトを参照してください。
SmartDocのメーリングリストがあります。
http://www.asahi-net.or.jp/~DP8T-ASM/java/tools/SmartDoc/ml_ja.html
メーリングリストの過去ログと検索ができます。（2005年4月30日現在公開中断しているようです)
http://sdocusersj.ml.nemui.org/maillist.html
SmartDocをインストールすると、2つの起動用ファイルがbinディレクトリに生成されます。
1.はUNIXシェルスクリプトで、2.はWindowsバッチファイルです。Cygwin32環境ではシェルスクリプトを使用するので、UNIX用シェルスクリプトを使います。
このsdocのあるディレクトリを環境変数PATHへ追加します。
<SmartDocインストールディレクトリ>/etcの下に、sdoc-mode.elとsdoc-helper.elがあるので、これをMeadowのlispディレクトリ(<meadow>/site-lisp等)にコピーします。
次に、拡張子.sdocを読み込んだら自動的にsdoc-modeになるように.emacsに設定を追加します。
(setq auto-mode-alist
(append '(("\\.sdoc$" . sdoc-mode)) auto-mode-alist))
(setq sgml-quick-keys t)
(autoload 'sdoc-mode "sdoc-mode" nil t)
この設定でEmacs上でファイルを編集しようとするときに、DTDのないwell-formedな場合にタグで属性を記述するためにダブルクォーテーション"をキー入力すると、&;qtに置き換わってしまいます。そこで、拡張子がxmlのファイルを編集するときにはダブルクォーテーションのキーバインドを無効にします。
(add-hook 'sdoc-mode-hook
(lambda ()
(when (string-match "\\.sdoc$" (buffer-name))
(local-unset-key "\""))))
SmartDocファイル保存時に、自動的に<date>タグの中に更新日時を展開できるようにMeadow(Emacs)のtime-stamp機能と組み合わせます。「Meadow-紹介マニアMoinMoin」ページで公開されていたものを追加したものです。（日時フォーマットで曜日を削除し、時刻帯を追加するよう修正）
上記のadd-hookと合わせて一つのlambda式で記載しています。
(add-hook 'sdoc-mode-hook
(lambda ()
(when (string-match "\\.sdoc$" (buffer-name))
(local-unset-key "\""))
;; "<date></date>"の自動更新
(set (make-local-variable 'time-stamp-start) "<date>")
(set (make-local-variable 'time-stamp-end) "</date>")
(set (make-local-variable 'time-stamp-format) "%04Y/%02m/%02d %02H:%02M:%02S %Z")
(set (make-local-variable 'time-stamp-line-limit) 30)
;; auto time-stamp
(add-hook 'local-write-file-hooks 'time-stamp)
(auto-fill-mode)))
Meadow 3で、C-c C-c（sdoc-comile)実行時に、以下のエラーが発生しました。仮対処としてとりあえず上記add-hookの中に、(setq compilation-read-command nil) を追記して回避しました。
sdoc-compile-all: Symbol's value as variable is void: compilation-read-command
| C-c C-c | バッファのSmartDoc文書に対してsdocコマンド実行 |
| C-u C-c C-c | プレビュー。プレインテキストでフォーマットされる。 |
| C-c C-k | ? sdoc-kill-content |
| C-c C-s C-p | SmatDoc文書の雛形を生成する |
| C-c C-s C-e | ? sdoc-use-entities |
| C-c C-s C-r | ? sdoc-make-table-records |
| C-c C-s C-a | ? sdoc-insert-internal-link |
| C-c C-s C-t | ? sdoc-auto-id-title |
Meadowでsdoc-modeの設定をしていると、簡単にとっつけます。まずMeadowで作成したい文書ファイル名を開きます。たとえば、how2smartdoc.sdocを作成するとします。
language : ja encoding : Shift_JIS title : How to write a SmartDoc documentと入力すると、ＳｍａｒｔＤｏｃのＸＭＬ文書の雛型が生成されます。下線部が入力したものです。
<?xml version='1.0' encoding='Shift_JIS' ?> <doc xml:lang='ja'> <head> <title>How to write a SmartDoc document</title> </head> <body> </body> </doc> |
head部では、雛型で生成されるtitleのほか、author, date, hp, email, abstractが記述できます。ステップ1で作成された雛型に追加して記述します。下記の例ではhead部で記述できる要素を一通り指定してみましたが、必須ではないので書かない要素があってもOKです。
<?xml version='1.0' encoding='Shift_JIS' ?> <doc xml:lang='ja'> <head> <title>How to write a SmartDoc document</title> <author>これがauthorの記述です</author> <date>これがdateの記述です</date> <hp>http://this.is.hp-element/</hp> <email>this.is@email.element</email> <abstract> ここにabstractの記述を書いています。abstractなので、 すこし長い文章を書いてみますが、面白いことが浮かばないので、 つまらないことをつらつら書いているだけになってしまいました。 </abstract> </head> <body> </body> </doc> |
ステップ2の段階で、いったんSmartDocによる文書生成を実行してみます。Meadow上から、C-c
C-cと打ちます。すると、sdocが起動されます。誤りがなければ、実行後how2smartdoc.htmlというHTMLファイルが生成されます。オプション指定をしていないので、デフォルトのHTML4形式のファイルになっています。
注）Meadowを起動するとき、環境変数PATHにsdocのあるディレクトリを指定しておく必要があります。
では、body部の記述に移ります。body部の構造は、TeXやHTMLのように章構造が文章の基本構造になります。
| SmartDocのタグ | 意味 |
| part | 部 |
| chapter | 章 |
| section | 節 |
| subsection | ： |
| subsubsection | ： |
実際に記述してみます。
<body> <part title="これはpart要素です"> body部は、章構成が基本となっています。 一番大きなレベルはpartとなります。 partの見出しは、partタグの属性titleで指定しています。 <chapter title="これはchapter要素です"> part部の1つ下に位置するのがchapterです。 chapterの見出しもtite属性で指定します。 <section title="これはsection要素です"> chapter部の1つ下に位置するのがsectionです。 sectionの見出しもtitle属性で指定します。 <subsection title="これはsubsection要素です"> sectionの下にはsubsectionがあります。見出しは同様title属性で指定します。 <subsubsection title="これはsubsubsection要素です"> subsectionの下にはsubsubsectionがあります。ふうっ。 見出しは同様title属性です。 </subsubsection> </subsection> </section> </chapter> </part> <appendix title="これはappendixです"> appendixというのがあったので記述してみました。 </appendix> <chapter title="これはpartの外側に置いたchapterです"> このように、partタグの中に入れずに独立してchapterを置くこともできます。 </chapter> <section title="これはpart,chapterの外側に置いたsectionです"> sectionも独立して置いてみました。 </section> <subsection title="これはpart,chapter,sectionの外側に置いたsubsectionです"> subsectionも同じように独立して置いてみました。 今回はこんなもんです。 </subsection> </body> </doc> |
これを、HTML形式に変換してみます。前回はMeadow上からC-c C-cでHTML4形式に変換してみましたが、今度はHTML3形式とHTML4形式の両方を生成してみます。
$ sdoc -format:html3 how2smartdoc.sdoc
$ sdoc -format:html3,html4 -packager:dir how2smartdoc.sdochtml形式は3,4ともに拡張子.htmlに生成されるので、同じファイルに出力してしまいます。そこで、出力先を別々のディレクトリに指定(-packager:dir)します。すると
$ ls -F how2smartdoc.sdoc html3/ html4/ $ ls html3 how2smartdoc.html $ ls html4 how2smartdoc.html
表の書き方は何通りかあります。
まず下記のような表を生成したいとします。
| 航路 | 便名 | 所属 |
|---|---|---|
| ガニメデ49 | GSL101 | ガニメデ宇宙旅客輸送 |
| タイタン221 | FSS233 | フェデレーションスペース |
最も簡単なのは、カンマ","で区切った形を使うものでしょう。
<table title="外宇宙定期便就航表"> <thead> 航路,便名,所属 </thead> <tbody> ガニメデ49,GSL101,ガニメデ宇宙旅客輸送 タイタン221,FSS233,フェデレーションスペース </tbody> </table> |
これだと、タグをそれほど書かなくても簡単に表を記述することができます。ただし、表のセルを連結するといったことができません。
正式な書き方。タグをいちいち書くのがその1に比べると大変です。
<table title="外宇宙定期便就航表"> <thead> <tr> <th>航路</th> <th>便名</th> <th>所属</th> </tr> </thead> <tbody> <tr> <td>ガニメデ49</td> <td>GSL101</td> <td>ガニメデ宇宙旅客輸送</td> </tr> <tr> <td>タイタン221</td> <td>FSS233</td> <td>フェデレーションスペース</td> </tr> </tbody> </table> |
では、なぜこの書き方をするかというと、複数セルを連結したり、表の中で文字を左・右・中寄せしたりして、複雑な表設定をおこなうことができるからです。
下記のように、セルが複数連結した表を作成する
| 型式 | グレード | 所属 |
|---|---|---|
| ファサード | アルファ | マーシャルスペース |
| ベータ | ガニメデ宇宙旅客輸送 | |
| メメント | フェデレーションスペース | |
HTMLのタグと同様、<th><td>に属性rowspan, colspanを使用する。
<table title="外宇宙航行船型式と採用会社"> <thead> <tr> <th>型式</th> <th>グレード</th> <th>所属</th> </tr> </thead> <tbody> <tr> <td rowspan="2">ファサード</td> <td>アルファ</td> <td>マーシャルスペース</td> </tr> <tr> <td>ベータ/td> <td>ガニメデ宇宙旅客輸送</td> </tr> <tr> <td colspan="2">メメント</td> <td>フェデレーションスペース</td> </tr> </tbody> </table> |
表に注記書きを付け加えます。<tnote>タグを使います。<tnote>タグの中には、<ul>もしくは<dl>を記述することができます。
<table title="外宇宙定期便就航表"> <thead> 航路,便名,所属 </thead> <tbody> ガニメデ49,GSL101,ガニメデ宇宙旅客輸送 タイタン221,FSS233,フェデレーションスペース </tbody> <tnote> <ul> <li>航路は木星・土星系のみ表記</li> <li>便名は太陽系惑星航行機関コードによる</li> </tnote> </table> |
文章中に挿入する図と、独立した図と2つがあります。
ガニメデ宇宙旅客輸送社の昨年の輸送実績を<a href="fig:lastyear1"/>に示します。 <figure id="fig:lastyear1" src="images/lastyear1.png" title="図1.1-1 実績（１）"/> |
文章中に、ハイパーリンクを記述することができます。リンクには、文書内の要素（図・表・各見出し等）と、文書外（WebのURL等）とがあります。
| 参考にしたアイテムは<a href="#参考">参考の節</a>に示します。 <section title="参考"> 参考として、・・・ |
リンク先文書内要素のタグのtitle属性に記述した文字列に#をつけて指定することができます。または、リンク先文書内要素のタグにid属性を指定すると、そのid属性に記述した文字列に#をつけて指定します。
| <a href="http://www.asahi-net.or.jp/~DP8T-ASM/java/tools/SmartDoc/index_ja.html">SmatDocのホームページ</a> |
文章中では、ハイパーリンクで文献名を指定します。文章の最後に<bibliography>で文献を列挙します。
惑星間航行における太陽風利用については、<a href="#bok:planetsPhysics"> 惑星間力学と太陽風</a>に詳しく述べられている。 : <bibliography> <book id="bok:planetsPhysics"> <author>Dr. Pedro Zabinsky</author> <title>惑星間力学と太陽風</title> <publisher>太陽系科学出版</publisher> <year>2031</year> </book> ： </bibliography> </body> </doc> |
文献の<book>タグのid属性で名前にbok:と付けているのは便宜上です。
SmartDocはプログラムのソースを記述する専用のタグを持っています。
<program title="MyJavaHello.java">
<![CDATA[
public class MyJavaHello {
public static void main(String[] args) {
System.out.println("Hello, Java World!");
}
}
]]>
</program>
|
CDATAで囲んでいるのは、XMLファイルでは'<'や'>'を使用することができないためです。
プログラムのソースは変更頻度が高いので、コピー＆ペーストでSmartDoc文書に取り込むよりは、外部ファイルからSmartDocコンパイル時に取り込む方がスマートです。
<program title="MyJavaHello.java" src="src/MyJavaHello.java" /> |
ソースコードの中から関数部分だけをSmartDoc文書に取り込むこともできます。javasrcKeywordで指定した正規表現にマッチした行を切り出します。ただし、その行に開き中括弧('{')があるときは、対応する閉じ中括弧('}')までのブロックを切り出します。
<program title="MyJavaHelloのmainメソッド" javasrcKeyword="void main" src="src/MyJavaHello.java" /> |
Javaのソースコードに文法に応じた色づけをして見やすくします。
<program title="HelloWorld.java" normalizer="javasrc"
javasrcSyntaxHilight="true">
<![CDATA[
public class HelloWorld {
:
} // HelloWorld
]]>
|
デフォルトは75桁で折り返す設定となっています。変更する場合は、programタグのprogramWidth属性で指定します。
SmartDocは、コンソール画面でのコマンド入力と結果表示を表現する専用のタグを持っています。
<console title="文字コードを指定してコンパイル"> D:\work> javac -encoding EUCJIS jp/gr/java_conf/torutk/hello/HelloWorld.java Hello, world! D:\work> </console> |
ソースコードと同様表示内で'<'、'>'や'&'などを使用するときは、<![CDATA[ 〜 ]]>で囲むとよいでしょう。
デフォルトでは1行65文字で折り返す設定となっています。折り返し記号はデフォルトでは' \'です。
折り返し記号を変更する場合、consoleContSymbol属性で指定します。
折り返し桁数を変更する場合、consoleWitdh属性で指定します。
<console title="文字コードを指定してコンパイル" consoleWitdh="128" consoleContSymbol=" |"> D:\work> javac -encoding EUCJIS jp/gr/java_conf/torutk/hello/HelloWorld.java Hello, world! D:\work> </console> |
最新ベータ版（2006年11月29日版）を含めて上記問題があります。2007年6月4日版で解決されました。
SmartDocは、コンソール画面に関して文字列からプロンプトを識別し、プロンプトの後ろから改行までをユーザー入力文字と認識してタグ付け（強調表示）します。
プロンプトの識別は、デフォルトでは1行目の行頭から>までとなります。これを別なプロンプト記号に変更する場合は、以下のどちらかの属性で指定します。
2行目以降にプロンプト行がある場合、以下の属性を指定します。
<console title="文字コードを指定してコンパイル" consolePrompt="$ " consolePromptRange="*"> work$ javac -encoding EUCJIS jp/gr/java_conf/torutk/hello/HelloWorld.java work$ java jp.gr.java_conf.torutk.hello.HelloWorld Hello, world! work$ </console> |
たとえば、節（section）ごとに別々のファイルに記述して、それらをまとめて１つのコンテンツとして扱うとします。
bookreview.sdoc
|
+--- oointro.sdoc
<body> <chapter title="オブジェクト指向開発技術"> <section src="oointro.sdoc"> </section> </chapter> </body> |
まず、sectionタグの属性を通常のtitleではなく、src属性を指定して値には独立させるファイル名を記述します。そして、そのままsectionタグを閉じます。
<?xml version='1.0' encoding='Shift_JIS' ?> <doc xml:lang='ja'> <head> <title>オブジェクト指向入門関連書籍</title> <author>高橋 徹</author> <hp>http://www.alles.or.jp/~torutk/</hp> <email>torutk@alles.or.jp</email> <date></date> </head> <body> <subsection title="オブジェクト指向がわかる本"> <subsubsection title="概要"> これからオブジェクト指向に取り組む人に、オブジェクト指向の 基本的な考え方を統一的に理解してもらうことを狙いとした本。 </subsubsection> </subsection> </body> </doc> |
分割されるファイルは、それ自身で完結したSmartDoc文書として記述します。ここでポイントは、分割の単位がsectionであり、これは上位のファイルでタグを記述しているので、分割されるファイルではsectionタグは書かずにその下のタグ〔この例ではsubsection）から使います。また、sectionタグのtitle属性は上位のファイルでは省略されてましたが、統合されるときには分割された文書のtitle要素を使います。
<body> <chapter title="オブジェクト指向開発技術"> <section title="オブジェクト指向入門関連書籍"> </section> </chapter> </body> |
ある程度大きな文書を書いていると、HTMLではファイルサイズが大きくなりすぎてブラウザでの閲覧に適さなくなってきます。そのときは、生成されるHTMLを複数に分割します。分割する単位は文章の見出しで指定できます。HTML4.0, HTML3.2, JavaHelpのページ分割が有効になります。
-splitオプション。-split:[part|chapter|section|subsection|subsubsection] |
ヘッダとフッダに指定したファイルを取り込みます。prologueはタイトルの下に入ります。
<head> <header> <native locale="ja" src="header_ja.html" format="html" /> <native locale="en" src="header_en.html" format="html" /> </header> <prologue> <native locale="ja" src="prologue_ja.html" format="html" /> <native locale="en" src="prologue_en.html" format="html" /> </prologue> <footer> <native locale="ja" src="footer_ja.html" format="html" /> <native locale="en" src="footer_en.html" format="html" /> </footer> </head> |
見出しに番号を振っていきます。
-html4.numberedTitleオプション |
前書き、謝辞、後書き、などには番号をつけないでおきたいところです。この場合、属性にsequencable="false"を指定しておきます。
<chapter title="謝辞" sequencable="false"> ありがとう </chapter> <chapter title="導入編"> ここには通し番号が付けられます。 </chapter> |
SmartDoc文書は標準ではHTML3/HTML4/LaTeX/JavaHelp形式の出力を行います。この他、プレインテキスト形式とPureSmartDoc XML形式があります。PDFファイルを生成する場合は、このいずれかの形式からPDF形式に変換することになります。
現時点でもっとも安定しているのは、1.のLaTeX経由かと思います。
インターネットには豊富な情報があります。
format=latex2e toc=true latex2e.driver=dvipdfm latex2e.ref=HyperRefLaTeX2eRefHandler |
Adobe Reader 6.0(Windows)では、しおりの日本語が化けてしまいます。これは、しおりの日本語がUnicodeでないといけないためです。LaTeXの中にout2uniというコマンドがあるので、これを使用します。以下のURLに対処方法が載っていました。
<figure>要素でGIF形式を読み込むように記述していると、LaTeX形式に変換後TeX処理系でエラーが発生します。PNG形式ならOKでした。
TeX処理系でエラーとなってしまいます。
デフォルトではTeXは表のセルの文章を改行なしに組み立てるので、表がページをはみ出てしまいます。そこで、以下のいくつかのTipsを組み合わせて対処します。
<table title="エアロック型式表">
<colgroups>
<col width="10em"/>
<col width="20em"/>
<col />
</colgroups>
<thead>
:
</thead>
<tbody>
:
</tbody>
</table>追記）IE6.0では、emという単位での指定ができません。Mozilla
1.4ではOKですが。そこで、%で指定するほうがよさそうです。ただ、％指定の場合、合計100%となるように指定してもLaTeXでは右側がページぎりぎりまで膨らむので、合計90%位になるようにするのがよさそう。
ということです。
$ sdoc sample.sdoc
$ platex sample
$ jbibtex sample
$ platex sample
$ platex sample
$ out2uni sample
$ platex sample
$ dvipdfm sample