<?xml version='1.0' encoding='Shift_JIS' ?>

<doc xml:lang='ja'>
<head>
<title>コマンド</title>
<author>浅海 智晴</author>
<date>2002年3月31日</date>
</head>
<body>

SmartDocの処理系は<tt>sdoc</tt>コマンドです。

本章では<tt>sdoc</tt>コマンドのパラメタについて説明します。

<section title="基本的な使い方">

<tt>sdoc</tt>コマンドの基本的な使い方は、コマンドの引数として
SmartDocファイルを指定するというものです。

たとえば、SmartDoc文書のファイルとして<tt>foo.sdoc</tt>を用意している場合には、
以下のようになります。

<console>
$ sdoc foo.sdoc
</console>

</section>

<section title="バージョンとヘルプの表示">

バージョンの表示には<tt>version</tt>オプションを指定します。

<console>
$ sdoc -version
Copyright(c) 1998-2001 ASAMI,Tomoharu. All rights reserved.
SmartDoc Version 0.7.1b (20011017) by ASAMI@Yokohama
</console>

ヘルプの表示には<tt>help</tt>オプションを指定します。

<console>
$ sdoc -help
Copyright(c) 1998-2001 ASAMI,Tomoharu. All rights reserved.
SmartDoc Version 0.7.1b (20011017) by ASAMI@Yokohama

Usage: sdoc [-options] [args...]

where options include:
[common]
  -version
	show version
  -help
  -?
	show help. (this message)
  -verbose[:true|false]
	enbale verbose output
  -toc[:true|false]
	make table of contents
...以下略
</console>

</section>

<section title="共通オプション">

<tt>sdoc</tt>コマンドは、生成するターゲット文書によってさまざまなパラメタを
取りますが、
<a href="#tab:commonOptions"></a>に示す
共通のオプションを持っています。

<table title="共通オプション" id="tab:commonOptions">
<thead>
オプション,意味,デフォルト,チューニング
</thead>
<tbody>
<tr>
  <td>verbose</td>
  <td>動作状況の表示を行なう。</td>
  <td>false</td>
  <td></td>
</tr>
<tr>
  <td>toc</td>
  <td>目次の作成を行なう。</td>
  <td>false</td>
  <td></td>
</tr>
<tr>
  <td>index</td>
  <td>索引の作成を行なう。</td>
  <td>false</td>
  <td></td>
</tr>
<tr>
  <td>locale</td>
  <td>生成するロケール。デフォルトではロケール指定なしでドキュメントの生成を行なう。</td>
  <td>(未設定)</td>
  <td>英語と日本語を出力する場合にはen,jaとなります。foo.sdocからHTML4.0を生成するとfoo_en.htmlとfoo_ja.htmlが生成されます。</td>
</tr>
<tr>
  <td>masterLocale</td>
  <td>ドキュメントの主となるロケール。masterLocaleとして指定されたロケールの出力ドキュメントのファイル名にはロケール名が付加されない。</td>
  <td>(未設定)</td>
  <td>localeにen,ja、masterLocaleにenと指定してfoo.sdocからHTML4.0を生成するとfoo.htmlとfoo_ja.htmlが生成されます。</td>
</tr>
<tr>
  <td>format</td>
  <td>出力するドキュメントフォーマット。デフォルトはHTML4.0。</td>
  <td>html4</td>
  <td>HTML4.0(html4)以外にHTML3.0(html3)、LaTeX2e(latex2e)、JavaHelp1.0(javahelp)、プレインテキスト(plain)、PureSmartDoc(pure)が指定できます。</td>
</tr>
<tr>
  <td>packager</td>
  <td>ファイル出力時のパッケージ方法。デフォルトでは通常のファイルとして出力。</td>
  <td>file</td>
  <td>file(ファイルに出力)以外にdir(サブディレクトリに分割), jar(JAR形式)、dirjar(サブディレクトリ上にJAR形式)が指定できます。</td>
</tr>
<tr>
  <td>split</td>
  <td>生成ファイルを指定された単位で分割。</td>
  <td>(未設定)</td>
  <td>部(part)、章(chapter)、節(section)、小節(subsection)、小小節(subsubsection)が指定できます。</td>
</tr>
</tbody>
</table>

</section>

<section title="formatオプション">

SmartDocでは、同一のソース文書から、用途に応じて複数のターゲット文書を
出力し分けることができます。
SmartDoc 1.0では以下のターゲットの出力をサポートしています。

<ul>
  <li>HTML 4.0</li>
  <li>HTML 3.2</li>
  <li>LaTeX2e</li>
  <li>プレインテキスト</li>
  <li>JavaHelp 1.0</li>
  <li>PureSmartDoc 1.0</li>
</ul>

これらのターゲットの生成を行なう機能をSmartDocではジェネレータと
呼んでいます。
<tt>sdoc</tt>コマンドで使用するジェネレータの指定には<tt>format</tt>
オプションを用います。

例えば、LaTeX2eを生成する場合には以下のようになります。

<console>
$ sdoc -format:latex2e foo.sdoc
</console>

<tt>format</tt>オプションでは、複数のジェネレータを同時に指定することが
できます。
ジェネレータの区切り記号には「,」を使用します。
この場合、指定したフォーマットの文書が同時に作成されます。

例えば、HTML 4.0とLaTeX2e、プレインテキストを同時に生成する場合には
以下のようになります。

<console>
$ sdoc -format:html4,latex2e,plain foo.sdoc
</console>

このコマンドの実行の結果、<tt>foo.html</tt>、<tt>foo.tex</tt>、
<tt>foo.txt</tt>の3つのファイルが生成されます。

<table title="tab:generatorOptions">
<thead>
ID,フォーマット,内容
</thead>
<tbody>
html4,HTML 4.0,W3C HTML 4.0。CSSおよびDynamic HTMLによる表現力豊かな表示
html3,HTML 3.2,W3C HTML 3.2。テキストベースの汎用的な表示
latex2e,LaTeX2e,LaTeX2e。ASCII pLaTeXとNTT jLaTeXの両方をサポート
plain,プレインテキスト,一般的なテキストファイル
javahelp,JavaHelp 1.0,JavaHelp形式。Javaアプリケーションのヘルプ用フォーマット
pure,PureSmartDoc 1.0,SmartDocの正規化フォーマット。外部コマンドによる加工用
</tbody>
</table>

</section>

<section title="tocオプション">

<tt>toc</tt>オプションは目次の生成を指示します。

<subsection title="目次の対象">

SmartDocでは以下のタグから目次を自動生成する機能を持っています。

<ul>
<li>part</li>
<li>chapter</li>
<li>section</li>
<li>subsection</li>
<li>subsubsection</li>
</ul>

今のところ図目次、表目次の自動生成は行ないません。(将来的にはサポート
したいと考えています)

</subsection>

<subsection title="指定方法">

目次の生成は<tt>toc</tt>オプションで指定します。
<tt>toc</tt>オプションが<code>true</code>なら目次を生成し、
<code>false</code>なら目次の生成を行ないません。
デフォルトでは<code>false</code>になっています。

<subsubsection title="コマンドオプションによる指定">

コマンドラインから目次の生成を指定する場合には以下のようになります。

<console>
$ sdoc -toc foo.sdoc
</console>

また以下の指定でも同じ意味です。

<console>
$ sdoc -toc:true foo.sdoc
</console>

ちなみに目次の生成を行なわないことを陽に指定したい場合には次のようにな
ります。

<console>
$ sdoc -toc:false foo.sdoc
</console>

</subsubsection>

<subsubsection title="プロパティファイルによる指定">

プロパティファイル(<tt>SmartDoc.properties</tt>)で指定する場合には
以下のようになります。
指定の詳細は後述の「プロパティファイルによる指定」を参照してください。

<program title="SmartDoc.properties">
toc=true
</program>

この設定が格納されているディレクトリ上で<tt>sdoc</tt>を起動すると
コマンドラインから<tt>toc</tt>オプションを指定したのと同じ効果を
得ることができます。
なおコマンドラインとプロパティファイルの指定が競合した場合にはコマンド
ラインの指定が優先されます。

</subsubsection>

</subsection>

<subsection title="ジェネレータ">

ジェネレータごとの目次の生成方法について説明します。

<subsubsection title="HTML">

HTML3.2, HTML4.0を生成する場合にはSmartDocが目次を自動生成します。
もちろん目次から各要素(section, subsectionなど)へのリンクは自動的に設
定されます。

</subsubsection>

<subsubsection title="LaTeX">

LaTeX2eの場合にはLaTeX2eの目次生成機能が使用されます。
具体的には<code>\tableofcontents</code>がタイトルと本文の間に挿入されます。

またページの開始は本文の先頭が1ページとなるよう設定されます。
つまり目次部分はページ数のカウントに入りません。

目次部分のページスタイルは<code>empty</code>となります。

</subsubsection>

</subsection>

</section>

<section title="localeオプション">

<tt>locale</tt>オプションは、出力する文書のロケールを指定するオプションです。
<tt>locale</tt>オプションを指定することにより、以下の2つの効果があります。

<ul>
  <li>SmartDoc文書内に記述されている要素の中で、<tt>locale</tt>オプションに適合するもののみを有効にする</li>
  <li>出力文書をロケールで指定した言語用にチューニングする</li>
</ul>

SmartDoc文書内には、複数のロケールの文章を混在して記述できます。
ロケールの指定は要素中の<code>locale</code>属性を用いて行います。
そして、<tt>sdoc</tt>コマンド実行時にlocaleオプションを指定することで、
指定されたロケール向けの文書を抽出することができるようになります。

<subsection title="localeの使用例">

localeを使用したSmartDoc文書は以下のようになります。
<code>locale</code>属性で、要素が所属するロケールを指定します。

<program src="src/command/locale.sdoc" id="prog:localeSdoc" title="sample.sdoc" encoding="Shift_JIS"/>

SmartDocでは、ここからlocaleオプションに指定されたロケールの内容を
抽出し、それに対応するHTML文書やLaTeX文書を生成します。

たとえば、上記のSmartDoc文書から、
日本語(localeがja)と英語(localeがen)の文書を抽出した文書の
イメージは以下のようになります。
(この文書はSmartDocのプログラム内部での仮想的なイメージなので実際には出力
されません。)

<program src="src/command/localeJa.sdoc" title="日本語" id="fig:localeJa" encoding="Shift_JIS"/>

<program src="src/command/localeEn.sdoc" title="英語" id="fig:localeEn"/>

<code>locale</code>属性が指定されていない要素は、すべてのロケールで
有効となり、<code>locale</code>属性が指定されている要素は、指定されたロケール
のみで有効となります。

</subsection>

<subsection title="コマンドの実行">

localeを指定したSmartDoc文書から、ロケールに対応したターゲット文書を
生成する場合には<tt>locale</tt>オプションを使用します。

まず日本語の場合ですが、これは<tt>locale</tt>オプションに'ja'を指定します。
この結果、<tt>sample.sdoc</tt>からHTML文書<tt>sample_ja.html</tt>が
生成されます。
この例から分かるように、<tt>locale</tt>オプションを指定した場合
ターゲットドキュメントの名前の後ろに&quot;_ロケール名&quot;が付加されます。

<console title="日本語文書を生成">
&gt; sdoc -locale:ja sample.sdoc
</console>

英語の場合には、<tt>locale</tt>オプションに'en'を指定します。
この場合には<tt>sample_en.html</tt>が生成されます。

<console title="英語文書を生成">
&gt; sdoc -locale:en sample.sdoc
</console>

</subsection>

<subsection title="複数ロケール">

<tt>locale</tt>オプションには複数のロケールを同時に指定することができます。
以下の例はロケールに'ja'(日本語)と'en'(英語)を指定しており、
この結果、日本語のHTML文書<tt>sample_ja.html</tt>と
英語のHTML文書<tt>sample_en.html</tt>が同時に生成されます。

<console title="日本語文書と英語文書を同時に生成">
&gt; sdoc -locale:ja,en sample.sdoc
</console>

</subsection>

<subsection title="ターゲット文書の種類">

<tt>locale</tt>オプションは、もちろんHTML文書以外をターゲットにした場合でも
使用することができます。

たとえば以下の例では、日本語のLaTeX2e文書を生成します。

<console title="LaTeX文書の生成">
&gt; sdoc -locale:ja -format:latex2e sample.sdoc
</console>

複数のロケールと複数のターゲット文書を同時に指定することもできます。

<console title="複数ロケール、複数ターゲットを指定">
&gt; sdoc -locale:ja,en -format:html4,latex2e,plain sample.sdoc
</console>

この例では、以下の6つの文書が生成されます。

<ul>
  <li>HTML 4.0の日本語文書</li>
  <li>HTML 4.0の英語文書</li>
  <li>LaTeX2eの日本語文書</li>
  <li>LaTeX2eの英語文書</li>
  <li>プレインテキストの日本語文書</li>
  <li>プレインテキストの英語文書</li>
</ul>

</subsection>

</section>

<section title="masterLocaleオプション">

<tt>locale</tt>オプションを指定すると、生成された文書のファイル名に
ロケール名が付加されます。
<tt>masterLocale</tt>オプションを併用することで、1つのロケールに限り
ロケール名が付加されることを抑止することができます。

<console title="masterLocaleオプション">
&gt; sdoc -locale:en,ja -masterLocale:en index.sdoc
</console>

この例では、以下のファイルが生成されます。

<ul>
  <li><tt>index.html</tt>(英語)</li>
  <li><tt>index_ja.html</tt>(日本語)</li>
</ul>

</section>

<section title="packagerオプション">

SmartDocの生成する生産物は、複数個のファイルとなることがあります。
デフォルトでは、すべてsdocコマンドを実行したディレクトリ上に作成されますが、
<tt>packager</tt>オプションを使用することで、生成物の格納方式を細かく制御
できます。

<table title="packagerのパラメタ" id="tab:packagerList">
<thead>
方式,内容
</thead>
<tbody>
file,ファイルに出力
dir,サブディレクトリに分割して出力
jar,JAR形式で出力
dirjar,サブディレクトリ上に分割してJAR形式で出力
</tbody>
</table>

<subsection title="file">

生産物をすべて通常のファイルとして生成します。
<tt>packager</tt>オプションのデフォルト値となっています。

<console>
&gt; sdoc -packager:file -format:html4,latex2e sample.sdoc
</console>

この例では、カレントディレクトリ上に<tt>sample.html</tt>と<tt>sample.tex</tt>
が生成されます。

</subsection>

<subsection title="dir">

生産物をフォーマットごとのサブディレクトリ上に作成します。

<console>
&gt; sdoc -packager:dir -format:html4,latex2e sample.sdoc
</console>

この例では、ディレクトリ<tt>html4</tt>の配下に<tt>sample.html</tt>が、
ディレクトリ<tt>latex2e</tt>の配下に<tt>sample.tex</tt>が生成されます。
ディレクトリが存在しない場合にはディレクトリも作成されます。

</subsection>

<subsection title="jar">

生産物をフォーマットごとのJARファイルとして作成します。

<console>
&gt; sdoc -packager:jar sample.sdoc
</console>

この例では、<tt>sample.html</tt>が格納された<tt>sample.jar</tt>が生成されます。
なお<tt>packager</tt>にjarを指定した場合は、複数のフォーマットを同時に
生成することはできません。

</subsection>

<subsection title="dirjar">

生産物をフォーマットごとのJARファイルとして作成し、フォーマットごとの
サブディレクトリに格納します。

<console>
&gt; sdoc -packager:dirjar -format:html4,latex2e sample.sdoc
</console>

この例では、ディレクトリ<tt>html4</tt>の配下に<tt>sample.html</tt>が
格納されたJARファイル<tt>sample.jar</tt>が、
ディレクトリ<tt>latex2e</tt>の配下に<tt>sample.tex</tt>が格納された
JARファイル<tt>sample.jar</tt>が生成されます。
ディレクトリが存在しない場合にはディレクトリも作成されます。

</subsection>

</section>

<section title="splitオプション">

SmartDocでは、生成されるターゲット文書を指定された単位に分割するための
機能として<tt>split</tt>オプションを用意しています。
デフォルトでは<tt>split</tt>オプションには何も設定されておらず、
ターゲット文書は分割されません。

<tt>split</tt>オプションには
<a href="#tab:splitParams"></a>
のパラメタを指定できます。

<table title="splitオプションのパラメタ" id="tab:splitParams">
<thead>
パラメタ,意味
</thead>
<tbody>
なし,分割しない
part,部単位で分割
chapter,章単位で分割
section,節単位で分割
subsection,小節単位で分割
subsubsection,小小節単位で分割
</tbody>
</table>


<tt>split</tt>オプションは以下のターゲット文書で有効です。

<ul>
  <li>HTML 4.0</li>
  <li>HTML 3.2</li>
  <li>JavaHelp</li>
</ul>

これ以外のターゲット文書に適用しても、分割処理は行われません。

</section>

<section title="プロパティファイルによる指定">

SmartDocを1回だけ起動するのであれば、
多少オプションの数が多くても、
コマンドラインからオプションを指定することはそれほど問題ではありません。

しかし、文書を作成する場合、何回も微調整を繰り返すのが普通であり、
その結果の確認のためにはSmartDocも頻繁に起動することになります。
このような場合には、オプションの指定をファイルに保存しておき、何回も
再利用できると便利です。

SmartDocでは、この目的でプロパティファイルの機能を用意しています。

<subsection title="問題の例">

たとえばfoo.sdocからHTML4.0とLaTeX2eの目次付きのドキュメントを生成し、
生成されたドキュメントは個別のディレクトリに格納し、LaTeX2eのオプショ
ンとして<code>a4j</code>、マクロとして<code>ascmac.sty</code>,
<code>array.sty</code>, <code>alltt.sty</code>を使うとすると以下のよう
になります。

<console>
$ sdoc -format:html4,latex2e -packager:dir -toc
-latex2e.option:a4j -latex2e.box:AscmacLaTeX2eBoxHandler 
-latex2e.table:ArrayLaTeX2eTablehandler
-latex2e.program=AllttLaTeX2eProgramHandler 
-latex2e.console=AllttLaTeX2eConsoleHandler foo.sdoc
</console>

これを毎回手で入力するのではたまりませんね。

もちろん<code>make</code>やシェルスクリプトで実行時のオプションを指定
するようにしても良いのですが、用途によってはSmartDocの持っているプロパ
ティファイル機能を利用すると便利です。

</subsection>

<subsection title="使い方">

SmartDocはコマンドを実行したディレクトリ上に
<code>SamrtDoc.properties</code>という名前のファイルがあると、このプロ
パティファイルの設定を利用します。

<code>SmartDoc.properties</code>の文法は通常のJavaのプロパティファイル
と同じで&quot;名前=値&quot;の形式です。
&quot;#&quot;でコメントも記述できます。

問題点で上げたオプションをこの<code>SmartDoc.properties</code>に記述す
ると以下のようになります。
一つポイントになるのは先頭にある<code>argument0</code>というプロパティ。
これは通常の引数を表しています。

<program title="SmartDoc.properties">
argument0=foo.sdoc
toc=true
format=html4,latex2e
packager=dir
latex2e.option=a4j
latex2e.box=AscmacLaTeX2eBoxHandler
latex2e.table=ArrayLaTeX2eTableHandler
latex2e.program=AllttLaTeX2eProgramHandler
latex2e.console=AllttLaTeX2eConsoleHandler
</program>

こうしておけば<code>sdoc</code>コマンド一発でドキュメントの生成が行な
われます。

<console>
$ sdoc
</console>

</subsection>

<subsection title="設定例">

筆者が普段使っている設定を<a href="#doc"></a>、<a href="#web"></a>に示します。

<program id="doc" title="設定例(レポート)">
argument0=foo.sdoc
verbose=true
toc=true
index=true
format=html4,html3,latex2e,javahelp
packager=dir
html4.dynamic=DeepHTML4DynamicHandler
latex2e.option=a4j
latex2e.package=times
latex2e.image=DVIPSLaTeX2eImageHandler
latex2e.box=AscmacLaTeX2eBoxHandler
latex2e.table=ArrayLaTeX2eTableHandler
latex2e.ref=HyperRefLaTeX2eRefHandler
latex2e.program=AllttLaTeX2eProgramHandler
latex2e.console=AllttLaTeX2eConsoleHandler
latex2e.imageLoc=tp
</program>

<program id="web" title="設定例(Webページ)">
argument0=foo.sdoc
verbose=true
locale=en,ja
masterLocale=en
html4.css.url=../../../jaba2s.css
html4.css.include=link
</program>

</subsection>

</section>

</body>

</doc>
