# コマンド

浅海 智晴
2002年3月31日

SmartDocの処理系はsdocコマンドです。

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

# 基本的な使い方

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

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

$ sdoc foo.sdoc

# バージョンとヘルプの表示

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

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

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

$ 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 ...以下略

# 共通オプション

sdocコマンドは、生成するターゲット文書によってさまざまなパラメタを 取りますが、 に示す 共通のオプションを持っています。

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

# formatオプション

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

- HTML 4.0
- HTML 3.2
- LaTeX2e
- プレインテキスト
- JavaHelp 1.0
- PureSmartDoc 1.0

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

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

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

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

$ sdoc -format:html4,latex2e,plain foo.sdoc

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

ID,フォーマット,内容
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の正規化フォーマット。外部コマンドによる加工用

# tocオプション

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

## 目次の対象

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

- part
- chapter
- section
- subsection
- subsubsection

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

## 指定方法

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

コマンドオプションによる指定

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

$ sdoc -toc foo.sdoc

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

$ sdoc -toc:true foo.sdoc

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

$ sdoc -toc:false foo.sdoc

プロパティファイルによる指定

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

SmartDoc.properties

toc=true

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

## ジェネレータ

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

HTML

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

LaTeX

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

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

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

# localeオプション

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

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

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

## localeの使用例

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

sample.sdoc

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

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

日本語

英語

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

## コマンドの実行

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

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

日本語文書を生成

> sdoc -locale:ja sample.sdoc

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

英語文書を生成

> sdoc -locale:en sample.sdoc

## 複数ロケール

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

日本語文書と英語文書を同時に生成

> sdoc -locale:ja,en sample.sdoc

## ターゲット文書の種類

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

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

LaTeX文書の生成

> sdoc -locale:ja -format:latex2e sample.sdoc

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

複数ロケール、複数ターゲットを指定

> sdoc -locale:ja,en -format:html4,latex2e,plain sample.sdoc

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

- HTML 4.0の日本語文書
- HTML 4.0の英語文書
- LaTeX2eの日本語文書
- LaTeX2eの英語文書
- プレインテキストの日本語文書
- プレインテキストの英語文書

# masterLocaleオプション

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

masterLocaleオプション

> sdoc -locale:en,ja -masterLocale:en index.sdoc

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

- index.html(英語)
- index_ja.html(日本語)

# packagerオプション

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

方式,内容
file,ファイルに出力 dir,サブディレクトリに分割して出力 jar,JAR形式で出力 dirjar,サブディレクトリ上に分割してJAR形式で出力

## file

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

> sdoc -packager:file -format:html4,latex2e sample.sdoc

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

## dir

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

> sdoc -packager:dir -format:html4,latex2e sample.sdoc

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

## jar

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

> sdoc -packager:jar sample.sdoc

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

## dirjar

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

> sdoc -packager:dirjar -format:html4,latex2e sample.sdoc

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

# splitオプション

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

splitオプションには のパラメタを指定できます。

パラメタ,意味
なし,分割しない part,部単位で分割 chapter,章単位で分割 section,節単位で分割 subsection,小節単位で分割 subsubsection,小小節単位で分割

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

- HTML 4.0
- HTML 3.2
- JavaHelp

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

# プロパティファイルによる指定

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

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

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

## 問題の例

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

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

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

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

## 使い方

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

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

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

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

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

$ sdoc

## 設定例

筆者が普段使っている設定を、に示します。

設定例(レポート)

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

設定例(Webページ)

argument0=foo.sdoc verbose=true locale=en,ja masterLocale=en html4.css.url=../../../jaba2s.css html4.css.include=link