マニュアル

(EZDOC Version 7.3)

平成28年1月14日
CREA

1 はじめに

  仕事の上でも、個人的にもパソコンでいろいろな文書を作りますが、 使いやすく満足できるワープロソフトは未だにありません。

  EZDOC は、使い慣れたテキストエディタを使ってXMLに基づく文書ファイルを作り、 これをスタイルシートに基づいてHTML(注) に変換して表示する文書作成ツールです。 EZDOCを使うと文書の著者は、 表示形式や機械的に処理できる部分をシステムに任せて、 文書の内容の検討に集中できるようになります。

  EZDOC は、文書ファイルを書く時の規則を定めそれを説明するマニュアルと 変換のためのスタイルシート、 そしてその処理を簡単にかつ確実に実行するためのバッチファイルなどを セットにして提供します。 XMLやXSLTなど標準の技術を基礎とする EZDOC は、 オープンソースソフトウェアなど無償で公開されたソフトウェアを使用し、 特定メーカの技術等にしばられることのない文書ファイルを作ります。 さらに、幅広く認められた標準に基づくので Windows に限らず Linux および Mac で 共通に使用することができます。

  EZDOC として提供されるファイルは、画像を除くと全てテキストなので、 技術的な観点で処理の全てを確認することができます。 さらには XML の特徴を活かして EZDOC の機能を拡張したり、 別のシステムと連携を図ることも簡単です。 興味のある方は、文書作成ツールとしての利用だけでなく、 ここまで是非試してみて下さい。

 
(注)  従来 EZDOCでは、文書ファイルを HTML version4.1 に変換してブラウザで表示していました。 しかし、HTML ではリンクの URL に全角文字を使用することが好ましくなく、 また リンクが機能しない場合があります。 これに対処するため EZDOC version7.3 から文書ファイルを XHTML version1 に変換してブラウザに 表示するようにします。
XHTML version1 は、HTML version4.1 の要素と属性をXMLで再定義していて、 これらの間で要素や属性の考え方は同じです。 そこで EZDOC の説明においては必要が無い限り XHTML について、 これより広く普及している HTML をそのまま表記として使用します。ご了承下さい。

2 概要

2.1 機能

  EZDOC では、文書ファイルをHTMLに変換しますが、 HTMLといってもいわゆるWebのページ作りが目的ではなく、 ワープロで作るような文書を作ります。 本マニュアルが一つの例です。 EZDOC では、1ページの簡単な文書から、 小規模なソフトウェアのマニュアル程度の規模の文書を作ることを目標としています。

  EZDOCは、次の機能と特長を持ちます。
1) 標題や著者名など文書の枠組みを自動的に配置して表示します。 また、文書の内容となる段落の中に書く、 箇条書きや図表についても内容を自動的に配置します。
2) 章や節の番号や図表の番号などは自動的に生成します。 さらに本文で、これらの番号を誤りなく表記するために 「番号の参照」といった機能が用意されています。
3) 文書ファイルを HTML に変換するなどの処理は、 バッチファイルを用意してあるので、ダブルクリックなどで 簡単に処理できます。

  本書の説明では、XML に関連する内容が含まれています。 XML になじみのない方は、 ホームページ「ソフトの道具箱」に 掲載している「 XML文書について」に 本ソフトを使う上で必要な程度の簡単な説明がありますので一読して下さい。

2.2 動作環境

  EZDOCについては、次の環境で動作を確認しています。
# OS XSLTプロセッサ 備考
1) [windows系]
Windows 7

msxsl.exe
2) [linux系]
openSUSE 13.2

xsltproc
(libxml 20901, libxslt 10128, libexslt 817)

ファイル名に全角文字があると正常な処理ができません。
3) [Mac系]
OS X El Capitan 10.11.2

xsltproc
(libxml 20707, libxslt 10124, libexslt 813)

ファイル名に全角文字があると正常な処理ができません。

XSLTプロセッサは、XML文書をHTMLに変換する時に使います。 上の表のXSLTプロセッサはいずれも無償で配布されています。 本書は、Windows 系での利用に向けて記述してあります。 LinuxないしMacで利用する場合は、 バッチファイル ezdoc.bat に代えてシェルスクリプト ezdoc.sh を使います。 その他については、適宜読み替えて下さい。

  EZDOCは、Version 7.1 から、インストール先と文書ファイルを置くフォルダに関して 基盤フォルダの考え方に適合するように変更しました。 基盤フォルダに関しては、 ホームページ「ソフトの道具箱」に掲載している 「文書の分類と複製 」 を参照して下さい。 インストール先は基盤フォルダの下にしています。 また文書ファイルは基盤フォルダの子フォルダからひ孫フォルダまでに置くことを 推奨しますが、第7段階目のフォルダまで動作します。

3 文書ファイルの書き方

  この章では文書ファイルの書き方について説明します。 説明では書き方の例を付けるようにしているので、 例について試しながら理解を深めるためにあらかじめ EZDOC をインストールすることをお勧めします。 EZDOC のインストールについては、、 「付録(4)」と 「付録(5)」を参照して下さい。

 
図3.1 テンプレートの表示

3.1 文書ファイルの使い方と内容

  文書ファイルの具体的な書き方を説明する前に、 その使い方と内容について簡単に紹介します。 まず、「図3.1 テンプレートの表示」を見て下さい。 これは、文書ファイルのテンプレートとして EZDOCが用意する文書ファイルをそのままHTMLに変換して表示したものです。

  それでは、思いどおりに文書を作る第一歩として、 「図3.1」の 「最初の段落の内容」の部分を「Hello, world!」と変えた文書を作ってみましょう。

  まず最初に、基盤フォルダの下に適当な名前を付けて 作業用のフォルダを作ります。 そのフォルダの下に EZDOC ホームフォルダから "ezdoc.bat"を複写し、ダブルクリックして実行して下さい(注)
(注)  バッチファイルを実行すると「MS-DOSの窓」が開いて最後の行に、 「続行するには何かキーを押してください . . .」が表示されます。 この窓にはバッチファイルによる処理内容などが表示されます。 通常は、適当なキーを押して下さい。窓が閉じます。
なお、文書ファイルに誤りがある時の警告などもこの窓に表示されます。

  バッチファイルの最初の実行では次の3つのファイルが バッチファイルと同じフォルダに生成されます。
1) ezdoc.html 文書ファイルから変換したHTML
2) ezdoc.xml 文書ファイル(テンプレートの写し)
3) ezdoc.xsl スタイルシート
ここで確認のためHTMLをブラウザの上にドラッグ&ドロップして下さい。 「図3.1」と同じ内容が表示されます。 また、文書ファイルをテキストエディタで開いて下さい。 コメントの部分を除くとその内容は、 「図3.2」と同じと思います。

  それでは、文書ファイルを開いたテキストエディタで、 要素 pa の内容にある「最初の段落の内容」の部分を 「Hello, world!」と変えて下さい。 さらに「著者の名前」の部分を自分の名前に変えてみましょう。 ここで、テキストエディタの上書き保存を実行して再度 ezdoc.bat を実行し、 先のブラウザで[Alt-v]-[Alt-r](Altキーとvキーを同時に押し、 次にAltキーとrキーを同時に押す意味です)して、「最新の情報に更新」します。 その結果、表示が"Hello, world!"に変わり、名前の表示も変ったと思います。 これで、修正後の文書ファイルが出来上がり、HTMLへの変換も完了です。

  要素 pa は段落に、そして要素 author は、著者名に対応しています。 EZDOCでは、このように文書の内容を表示形式に対応した要素の内容として記述します。

  上の表示内容を少し細かく確認しましょう。 段落の内容の"Hello, world!"が、 章の番号に対してほぼ1文字分字下げされ、「以上」が付いています。 字の大きさに関しては、文書の標題、章の標題と段落の内容とで違っています。 テキスト文書をエディタで開いた時と違って、 文書としての体裁で表示されます。

  EZDOC を使った文書作成において中心となる文書ファイルの内容と使い方の基本は、 このように単純なものです。

 
図3.2 簡単な文書ファイルの例

3.2 文書ファイルの構成

  上で説明した「図3.2 簡単な文書ファイルの例」を使って、 文書ファイルの構成について説明します。

  文書ファイルの内容は、次のように分類できます。
1) XML文書としての宣言
2) EZDOCで定義する要素とその内容
a) 文書の枠組みを記述する要素
b) 段落の中を記述する要素、等
図3.2の最初の2行が、 XML文書としての宣言です。 第1行目は、このファイルがXML文書であることを示していて、 さらにこのファイルで使用している文字コードを定義します。 第2行目は、 このファイルを直接ブラウザで表示する時に適用するスタイルシートを定義します。 文書ファイルを直接ブラウザで表示することがなく、 後で説明する変換後のHTMLを表示するだけなら、第2行目は不要です。

  XML宣言における文字コードの指定では、次のような表記が使えます。

 
# 表記 コード
--- -------- ----------
1) Shift_JIS シフトJIS
2) EUC-JP 日本語EUC
3) UTF-8 UTF-8
4) UTF-16 UTF-16

  そして第3行目から最後までがEZDOCで規定している要素とその内容で、 これらの要素の書き方など使い方については、 次節以降で説明します。 これらの要素は次の2つに分類することができます。

 
最初は、「文書の枠組みを作る要素」です。 ルート要素 article や、文書の標題、 著者名を意味する、要素titleやauthorがこれに分類されます。 ここに分類される要素については、一覧を 「付録(1) 文書の枠組みを記述する要素」に示します。

次は、「段落の中を記述する要素」です。 これらは、段落を示す要素 pa の子ないし子孫として書きます。 これらには、先の例で見たような文字列と、 その外、箇条書きや表を書くための要素などがあります。 大半の要素は、HTMLにおける定義からの抜粋で、 他に一部EZDOC固有の要素があります。 これらの要素については「付録(2) 段落の中を記述する要素」に一覧としてまとめてあります。

3.3 文書の枠組みを作る要素

  それでは、 「文書の枠組みを作る要素」から具体的な書き方の説明を始めます。

3.3.1 標題(article/title)と副標題(subtitle)

  文書の標題は、ルート要素 article の子要素 title の内容として文字列で記述します。 要素を含むことはできません。 本書の説明において他の title という名称の要素と区別するために、 この要素の場合は、 article/title と表記することがあります。

  副標題については、要素 subtitle の内容として、文字列で記述します。

3.3.2 日付(date)と著者名(author)

  文書の作成日を示す日付は、要素 date の内容として文字列で記述します。

  著者名については、要素 author の内容として記述します。 ここには文字列の他、 改行を示す要素 br (第3.4.3項参照)が記述できます。 例えば氏名だけでなく部署名などを併記する時に使います。 要素 author には、 日付と著者名の表示幅を指定する属性 width を付けることができ、 これで表示幅を変更することができます。

3.3.3 前書き(preface)

  前書きは、要素 preface を使います。 中味は、段落の要素 pa (第3.3.6項参照) を使って書きます。 段落は複数書くことができます。 前書きは、表示において本文に対して、左右の幅が少し狭く、 他と区別しやすい形で表示されます。

3.3.4 章、節、項など(section)

  章は、要素 section を使って記述します。 子要素 title に章の標題を書きます。 中味は段落の要素 pa (第3.3.6項参照) を使って書きます。

  要素 section は、子要素 section を持つことができます。 この子要素も同様です。したがって要素 section は多重に書くことができ、 それぞれ、章、節、項に対応します。 章、節、項の表示では、 標題の前に"1"、"1.2"、"1.2.3"などの書式で番号が自動的に付きます。 属性 ref-id については、「第3.5.5項」で説明します。

3.3.5 付録(appendix)

  付録は、要素 appendix を使って書きます。 付録の標題を子要素 title の内容に書き、 中身は、子要素 pa に書きます。

  付録の場合も、章と同じように自動的に番号を付けます。 しかし、要素"section"のように多重に書くことはできません。 属性"ref-id"については、「第3.5.5項」で説明します。

3.3.6 段落(pa)

  一つの要素 pa が一つの段落に対応し、 要素 pa の内容には、文字列と段落の中を記述する要素を書くことができます。

  要素 pa は、要素 article の子要素、もしくは要素 preface 、 section 、 appendix の子要素として使います。 入れ子にして書くことはできません。

3.4 段落の中を記述する要素(その1)

  この節では、段落の中を記述する要素の内、 HTML と同じ書き方をする次の要素について説明します。 HTML と比べると使える要素と属性の種類が一部制限されています。

 
表3.1 要素 pa の子要素(その1)
# 要素名 機能
--- ---------- --------------------
1) a リンク
2) blockquote 引用
3) br 改行
4) center 中央揃え
5) dl 定義リスト
6) img 画像
7) pre 整形済みテキストの表示
8) small 小さく表示
9) table
10) ul, ol 箇条書き

  以下の説明においては、 要素の[書き方の例]とそれを表示した時の書式を[表示]に示しますので、 見比べて参考にして下さい。

3.4.1 リンク(a)

  Webのページやパソコン内の他の文書へのリンクを書くことができます。 他文書へのリンクを書くときのフォルダの区切りは、"\"も使えますが、 他との整合性を考慮し EZDOC では"/"を使うことを推奨します。

  [書き方の例]
<a href="image/ezdoc.html">ezdoc.html</a>
<br/>
<a href="http://www.yahoo.co.jp" target="abcde">Yahoo!Japan</a>

 
[表示]
ezdoc.html
Yahoo!Japan

[属性]
href リンク先のURLもしくはファイルへのパスを書きます。常に必要です。
target target 属性があるとリンク元を表示しているウィンドウとは別に 新しくウィンドウを開いてそちらにリンク先の内容を表示します。 属性値には、適当な名前を書きます。同じ名前のウィンドウが 既に開いている場合にはそのウィンドウに表示します。

3.4.2 引用(blockquote)

  他の文書から引用した文章などを書きます。引用を示すために、 要素 blockquote の外側の文章に対して、一段下げて内容を表示します。

  [書き方の例]
一般の文章は、この位置から表示されます。
<blockquote>
    引用した文章は、この位置から表示されます。
</blockquote>

 
[表示]
一般の文章は、この位置から表示されます。
引用した文章は、この位置から表示されます。

3.4.3 改行(br)

  文章の途中で改行するためには、空の要素 br を書きます。 書き方の例にもあるように、テキストエディタの改行は、 HTMLへの変換の段階で無視、もしくは空白1文字に置き換えられます。

  [書き方の例]
長い文章の
途中で
<br/>
改行する。
[表示]
長い文章の 途中で
改行する。

[brの属性]
clear 画像に対する文字列の回りこみを解除する(例: clear="all")。

3.4.4 中央揃え(center)

  文字列や図表などを中央に配置して表示します。

  [書き方の例]
<center>
    例えばタイトル
    <br/>
    その内容などの文章
</center>

 
[表示]
例えばタイトル
その内容などの文章

3.4.5 定義リスト(dl/dt/dd)

  用語などの定義には、定義リストの親要素 dl と子要素 dt と dd を使います。 要素 dt に定義する用語を、そしてその説明を要素 dd に書きます。

  [書き方の例]
<dl>
<dt>
    箇条書き
</dt>
    <dd>
        ulもしくはol/li要素を使って書きます。
    </dd>
<dt>
    用語定義のリスト
</dt>
    <dd>
        dl/dt/dd要素を使って書きます。
    </dd>
</dl>

 
[表示]
箇条書き
ulもしくはol/li要素を使って書きます。
用語定義のリスト
dl/dt/dd要素を使って書きます。

3.4.6 画像表示(img)

  要素 img を使って画像を表示することができます。常に空要素です。 実際の文書の作成に当たっては、 別途規定する図の要素 fig や写真の要素 photo を使う方が便利でしょう。 これらについては、次節で説明しています。

  [書き方の例]
<img src="image/sakura.jpg" height="120"/>

 
[表示]

[imgの属性]
align 画像に対して文字列の回りこみを可とする時、 画像の置き場所{left | right}。
src 表示する画像のファイル名を指定します(例: src="image/sakura.jpg")。
width 表示する画像の幅を指定します(例: width="100")。単位はピクセル。
height 表示する画像の高さを指定します(例: height="150")。単位はピクセル。
(注)widthかheightの一方を指定すると画像の縦横比を維持して表示されます。

3.4.7 整形済みテキストの表示(pre)

  テキストエディタで書いたとおりに表示します。 プログラムソースなどを書く時に使います。 要素 pre の中の文字は、通常の文章に比べ一段階小さく表示されます。 XMLの構文を書くときには、pre 要素の中でさらに "<![CDATA[" と "]]>" で表示する内容を囲います。

  [書き方の例]
<pre><!*[CDATA[
<article>
    ....(xml の構文等)
</article>
]]*></pre>
実際には上の書き方の例にある"*"は除いて下さい (ここでは表示のため止むを得ず付けています)

 
[表示]
<article>
    ....(xml の構文等)
</article>

3.4.8 小さく表示(small)

  一部の文字列を小さく表示する時に使います。

  [書き方の例]
大きく表示。
<small>小さく表示</small>

 
[表示]
大きく表示。 小さく表示

3.4.9 表(table/caption/tr/th/td)

  表は、要素"table"を使って書きます。 表に標題を付ける時は、要素"caption"に書きます。 表には、行(レコード、親要素"tr")を複数書くことができ、 要素"tr"にはさらに表題の要素"th"、 もしくはデータの要素"td"を各々複数書くことができます。

  1)表の基本的な書き方

  [書き方の例]
<table border="1" width="80%">
<caption>
    今日の在庫状況
</caption>
<tr><th>品目
    </th><th>単価
        </th><th>在庫
             </th></tr>
<tr><td>リンゴ
    </td><td>@150-
        </td><td>10コ
            </td></tr>
<tr><td>みかん
    </td><td>@80-
        </td><td>52コ
            </td></tr>
</table>

 
[表示]
今日の在庫状況
品目 単価   在庫
リンゴ @150- 10コ
みかん @80- 52コ

[tableの属性]
border 表の枠線を表示する時に使用します(例: border="1")。 値は枠線の太さを示します。 枠線を表示しない時は省略します。
width 表の横幅を指定します(例: width="200"、 width="50%")。単位はピクセル、 もしくは表示幅に対する割合(%)で与えます。
ref-id 「第3.5.5項」で後ほど説明します。

[trの属性]
align 横位置{left | center | right}を指定します(例: align="center")。
valign 縦位置{top | middle | bottom}を指定します(例: valign="bottom")。

属性"align"、"valign"は、 要素"tr"に含まれる子要素"td"ないし"th"のデフォルトとして作用します。

[thの属性]
width セルの幅を指定します(例: width="70"、 width="20%")。 単位は、ピクセル、もしくは表の幅に対する割合。
align trの属性と同じ書き方です。
valign trの属性と同じ書き方です。
colspan 横方向に結合するセルの数を指定します(例: colspan="2")。
rowspan 縦方向に結合するセルの数を指定します(例: rowspan="3")。
[tdの属性]
要素"th"の属性と同じです。

  2)align/valignの例

  [書き方の例]
<table border="1" width="80%">
<caption>
    今日の在庫状況
</caption>
<tr><th>品目
    </th><th>単価
        </th><th>在庫
            </th></tr>
<tr><td>
    <br/>
    リンゴ
    </td><td>@150-
        </td><td valign="bottom" align="right">10コ
            </td></tr>
<tr><td>みかん
    </td><td align="right">@80-
        </td><td align="right">52コ
           </td></tr>
</table>

 
[表示]
今日の在庫状況
品目 単価 在庫

リンゴ
@150- 10コ
みかん @80- 52コ

  3)colspan/rowspanの例

  [書き方の例]
<table border="1" width="80%">
<caption>
    今日の在庫状況
</caption>
<tr><th>種類
    </th><th>品目
        </th><th>単価
            </th><th>在庫
                </th></tr>
<tr><td rowspan="2">果物
    </td><td>リンゴ
        </td><td colspan="2">(在庫なし)
                </td></tr>
<tr>
    <td>みかん
        </td><td>@80-
            </td><td>52コ
                </td></tr>
</table>

 
[表示]
今日の在庫状況
種類 品目 単価 在庫
果物 リンゴ (在庫なし)
みかん @80- 52コ

3.4.10 箇条書き(ul/ol/li)

  箇条書きには、先頭に"・"を付けて表示する番号なしと、 先頭に番号をつけた番号付きがあります。 番号なしの場合は親要素"ul"、番号付きの場合は、親要素"ol"を使います。 どちらの場合も、箇条書きの個別の項目を子要素"li"に書きます。 要素"ul"の書き方から示します。

  [書き方の例]
<ul>
    <li>
        日本語
    </li>
    <li>
        英語
    </li>
</ul>

 
[表示]
日本語
英語

  番号付きの場合は、要素"ul"の代えて要素"ol"要素を使い、 要素"li"の使い方は同じです。 番号付き箇条書きの項目の中に再度番号付き箇条書きを書いた場合は、 内側の番号が、a)、b)... のように変わります。 番号付きの表示は、次のようになります。
[表示]
1) 日本語
2) 英語

3.5 段落の中を記述する要素(その2)

  ここでは、段落の中を記述する残りの要素などについて説明します。

 
# 要素 機能
--- ---------------------- -------------------------
1) dl-n 番号付き定義リスト。
2) fig 図。
3) photo 写真。
4) 内容に q-n を含む td テーブルの行(レコード)番号で q-n を置換えます。
5) tr-nc tr要素と同じ。ただし行番号の生成において参照しない。
6) ref 図表等の番号と表題の参照。

3.5.1 番号付き定義リスト(dl-n)

  定義する用語の前に番号を付ける定義リストです。 番号を付ける時は、定義リストの要素"dl"に代えて"dl-n"を使用し、 その他の要素"dt"と"dd"は定義リスト"dl"の場合と同じです。

  [書き方の例]
<dl-n>
<dt>一般の定義リスト
    </dt>
    <dd>要素dl/dt/ddを使って書きます。
        </dd>
<dt>番号付き定義のリスト
    </dt>
    <dd>dl-n/dt/dd要素を使って書きます。
        </dd>
</dl-n>
[表示]
1) 一般の定義リスト
要素dl/dt/ddを使って書きます。
2) 番号付き定義のリスト
dl-n/dt/dd要素を使って書きます。

3.5.2 標題付き図(fig)

  標題を付けた図を表示します。標題は、子要素"title"に書きます。

  [書き方の例]
<fig src="./image/sakura.jpg" height="100">
    <title>桜の花</title>
</fig>

 
[表示]
桜の花

  [figの属性]
ref-id 「第3.5.5項」で後ほど説明します。
(その他) 要素"img"と同じです。

3.5.3 写真(photo)

  標題を付けた写真を表示します。標題は、子要素titleに書きます。

  [書き方の例]
<photo src="./image/sakura.jpg" height="100">
    <title>桜の写真</title>
</photo>

 
[表示]
桜の写真

  [photoの属性]
ref-id 「第3.5.5項」で後ほど説明します。
(その他) 要素"img"と同じです。

3.5.4 テーブルのレコード番号の生成(内容に q-n を含む td と tr-nc)

  表の要素"td"の内容が、q-n の時、もしくは q-n から始まる時、 レコードの親要素"tr"が開始タグ"table"から出現した数をかぞえ、 q-n をこの値に置き換えます。 これを使うとレコードに順に番号を付けることができます。 この時、表題の要素"th"のレコードの要素"tr"があるとがずれてしまって、 具合が悪いことがあるのでこの時は、 要素"tr"に代えて"tr-nc"を使います。 要素"tr-nc"は、数える対象からはずしてあるので調整ができます。 要素"tr-nc"の他の特性などは、要素"tr"と同じです。

  [書き方の例]
<table border="1" width="80%">
<caption>
    今日の在庫状況
</caption>
<tr-nc><th>#
    </th><th>品目
        </th><th>単価
            </th><th>在庫
                </th></tr-nc>
<tr><td>q-n)
    </td><td>リンゴ
        </td><td>@150-
            </td><td>10コ
                </td></tr>
<tr><td>q-n)
    </td><td>みかん
        </td><td>@80-
            </td><td>52コ
                </td></tr>
</table>

 
[表示]
今日の在庫状況
# 品目 単価 在庫
1) リンゴ @150- 10コ
2) みかん @80- 52コ

3.5.5 図表などへの番号付けとその参照 (属性"ref-id"と要素"ref")

  EZDOCでは、章、節、...と付録には、常に自動的に番号を付けますが、 その他の要素にも番号を自動的に付け、 さらにそれらの番号と標題を文章の中で参照して表示することができます。 自動的に番号を付けることができる要素を次の表にまとめます。 番号は、次表の要素に属性 ref-id を付加するだけで表示されるようになります。
# 種別 要素 表記
-- ---------- ---------- ----------
1) fig
2) 写真 photo 写真
3) table
4) 章、節、… section(*) (なし)
5) 付録 appendix(*) 付録
(注) * 印の要素は、属性 ref-id の有無にかかわらず常に番号が付きます。 なお、番号付けの対象となる図、写真、表は要素 section の子孫の要素に限ります。
属性 ref-id には、参照する時の識別子として、適当な文字列を書きます。 ただ、文書の中の番号付けにおいて他の識別子と重複しないようにすることが必要です。

  番号付けの例として、写真に番号を付ける例を次に示します。

  [書き方の例]
<photo src="./image/sakura.jpg" ref-id="photo5" height="100">
    <title>桜の写真</title>
</photo>

 
[表示]
写真3.1 桜の写真

  本文中でこれら図表等の番号や標題について記述する時、 図表等に付いた番号や標題と本文に食い違いが生じないよう、 図表等を参照する要素"ref"を使うと便利です。 要素"ref"は次のように使います。

  [書き方の例]
上の写真の参照は、「<ref ref-id="photo5"/>」になります。
<br/>
標題を抑制する場合は、「<ref ref-id="photo5" swTitle="off"/>」になります。
<br/>
この項は、「<ref ref-id="番号参照"/>」です。

 
[表示]
上の写真の参照は、「写真3.1 桜の写真」になります。
標題を抑制する場合は、「写真3.1」になります。
この項は、「3.5.5 図表などへの番号付けとその参照 (属性"ref-id"と要素"ref")」です。

  [refの属性]
ref-id 参照する図表などの属性"ref-id"と同じ文字列を書きます。
swTitle 標題の抑制{off}

  定義されていない"ref-id"を書いた場合は参照した個所に次のように表示されます。
REF:"適当な文字列です"
図や表の番号は、これまでの例では章番号とその中の通し番号で構成されていますが、 文書の中での通し番号とすることができます。 変更の仕方については、「4.4 文書の体裁の変更」で説明します。

  図、写真、および表に関して、これらを前書きや付録に置く場合、 もしくは章を持たない文書などで章の外に置く場合で、 これらに番号を付ける時は、 デフォルトのままでは番号付けが正しく機能しません。 この場合は、文書の中での通し番号に変更する必要があります。

3.6 文書ファイルを書きやすくする工夫

  実はXMLに準拠した文書ファイルは、教科書どおりに書くと、 インデントが深くなったり、 内容がタグにはさまれていて修正する時に骨が折れたりします。 これらは、少しの工夫で大幅に改善できます。 XMLの特性を踏まえることがポイントです。 著者は、次のような点を実践してストレスを減らして書いています。
1) 段落の内容は、親の要素 pa との間に空行を置いて区別し、 インデントを止めて左端から書き始めます。
2) リストや表など内容の量が多くなる要素は左端から書き始め、 他との区別のため空行を前後に入れます。
3) 表(table要素)は、1列分のデータをテキストエディタの1行毎に分けて書き、 各行の開始位置も調整する (「3.4.9 表(table/caption/tr/th/td)」を参照)と、内容の修正や、 列の挿入、削除が、ずっと楽になります。
4) テキストエディタによっては、 タブ幅が標準で半角8文字になっているものがあります。 可能なら設定を2ないし4文字に変更すると入力とその確認が楽になります。

4 バッチファイルによるHTMLへの変換

  EZDOC においては、「3.1 文書ファイルの使い方と内容」等で説明してきたように、 基本はEZDOCホームから複写しただけのバッチファイルを実行してHTMLを生成しますが、 この他、目次を付けたHTMLとしたり、 文書の量が多い時など複数の文書ファイルを作ってこれらを統合して HTMLを生成したりすることができます。

  パラメータによって変りますが、 バッチファイルの実行によって生成されるファイルを次に示します。 こららは、全てバッチファイルが実効された作業フォルダに生成されます。
# ファイル名 必須 内容など
1) ezdoc.html HTML(ファイル)。
2) ezdoc.xml 文書ファイル
3) ezdoc.xsl (個別の)スタイルシート
4) ezdoc-ini.xml パラメータファイル。
同じ名前のファイルは置かないで下さい。 バッチで削除するので通常は見えません。
5) ezdoc-files.xml 複数の文書を統合する場合のファイル一覧。
6) ezdoc-index.html 目次つきHTMLの先頭ファイル。
7) ezdoc-integ.xml 複数文書を統合したファイル。
同じ名前のファイルは置かないで下さい。 バッチで削除するので通常は見えません。
8) ezdoc-left.html 目次付きHTMLの左フレーム(目次)。
必須の欄に○印があるファイルは、必ず存在し使用されます。

  この後、HTMLの生成において調整が可能な次の内容について説明します。
1) 目次の生成
2) 文書ファイル名の変更
3) 複数の文書ファイルの統合
4) 文書の体裁の変更
また、これらと合わせてHTMLへの変換時に発生するエラーメッセージと対処法を説明します。

4.1 目次の生成

  EZDOCの目次付きマニュアルと同じような目次が付いた文書を 次のようにして簡単に作ることができます。 バッチファイルの修正は、任意の時点で変更でき、 修正後の実行で目次のついた文書が生成されるようになります。

  バッチファイルの8行目を次のように変更して、保存します。
set INDEX=on
目次付きのHTMLを開くときは、ezdoc-index.html をブラウザで開きます。

4.2 文書ファイル名の変更

  一つのフォルダに複数の文書を置く場合などに文書のファイル名の変更が必要になります。 EZDOCの場合は文書ファイルとそれに関連したファイルを全て同じファイル名にする必要があります。 これらの変更は次のようにします。

  作業フォルダにバッチファイルを複写したら、 実行する前にそのファイル名を変更します (例:sample.bat)。 この後、これを実行すると生成されるファイルは全て"sample.xxxx"になり、 こうすると手間をかけずに名前を変えてHTMLを生成できます。
(注)
次の記号は、ファイル名の一部に使用することができません。
スラッシュ (/)、円記号 (\)、不等号記号 (<>)、アスタリスク (*)、疑問符 (?)、 ダブル クォーテーション (")、縦棒 (|)、コロン (:)、セミコロン (;) 、 空白、タブ
これに対して、例えば"ezdoc"として文書ファイルなどを生成、修正した後、 ファイル名を"sample"に変えるには、バッチファイル、文書ファイルの名前を変えます。 また、ezdoc-files.xmlがある時は、同様に名前を変えます。

  その上で、文書ファイルの2行目の内容を次のように変更します。 sample-file.xmlファイルの内容も適宜修正します。
<?xml-stylesheet type="text/xsl" href="./sample.xsl" ?>
残りのファイルはバッチファイルを実行して自動生成するのが良いでしょう。 その後の操作は、ファイル名を変える前と同様です。

4.3 複数の文書ファイルの統合

  EZDOC では文書ファイルを複数用意したあと、 これらを統合して一つのHTMLとすることができます。

  文書ファイルの用意においてはファイル名を変えて複数の文書ファイルを作成します。 この時、統合時のエラーに対処しやすくするために、 文書ファイルの各々がエラー表示されることなくHTML変換ができるところまで処理を進めます。 文書ファイルの用意ができたら、適当な文書のバッチファイルの10行目を次のように変更して保存し、 これを一度実行します。
set MULTI=on
バッチファイルの実行によってファイル ezdoc-files.xml が生成されるので、 テキストエディタでこれを開きます。 この時点の内容は、要素 files の下に要素 file が一つだけ存在します。 ここで、要素 files の下に統合する文書の数だけ要素 file を作り、 各々にファイル名を記入します。 この後、変更を保存して実行するれば統合されたHTMLが生成されます。

  統合後のHTML(ezdoc.html)の構成は次のようになります。
1) 文書の表題、副表題、日付、著者名、前書きは、 最初の要素 file で示される文書ファイルの内容が使われます。
2) 要素 section は、要素 file の順に従って並びます。
3) 付録は、最後にまとめられ、やはり要素 file で示されたファイルの順に並びます。
複数文書ファイルの統合と目次の生成は同時に指定することが可能です。

4.4 文書の体裁の変更

  EZDOCでは、文書の体裁を共通のスタイルシートで定義していますが、 個別に文書の体裁を変えることができます。 この体裁の変更に関して、次の3つの変更はEZDOCで簡便な方法を用意しています。
1) 文書の書体(フォント)をデフォルトのゴシック体から明朝体へ変更
2) 文書の書体の大きさを標準から、一回り小さなサイズに変更
3) 図番などの番号を、文書内の一連の番号に変更
個別に文書の体裁を変更するには、 文書ファイルと同じフォルダにあってこれにに対応しているスタイルシートを テキストエディタで開き、変更内容に応じて次に示すように修正します。 その後内容を保存してバッチファイルを実行すると、 体裁を変えたHTMLを生成することができます。

  1)書体(フォント)を明朝体へ変更

  明朝体への書体の変更は、"ezdoc.xsl"の次の3行の内、 中央の行をコメントにならない部分に複写します。
<!-- 文字の書体を明朝体に変更する時、次行をコメントでなくする
<xsl:variable name="font-face" select="'mincho'"/>
-->

  次のように変更するのが簡単です。
<!-- 文字の書体を明朝体に変更する時、次行をコメントでなくする
<xsl:variable name="font-face" select="'mincho'"/>
-->
<xsl:variable name="font-face" select="'mincho'"/>

  2)フォントサイズの変更

  書体を小さくする場合も、同様です。次の中央の行を コメントとならない部分に複写します。 なお、この指定は文書全般に作用するので部分的に小さくする場合は要素 small を使います。
<!-- 文字サイズを小さくする時、次行をコメントでなくする
<xsl:variable name="font-size" select="'smaller'"/>
-->

  3)図番などを文書内の一連の番号に変更

  図番などは、デフォルトでは章の中での通し番号になっていますが、 これを文書内での一連の番号に変更することができます。 この場合は次の中央の行をコメントでないようにします。
<!-- 図、表などの番号を文書の中での通し番号とする時、次行をコメントでなくする
<xsl:variable name="numbering" select="'article'"/>
-->

  また、上で述べた簡易な変更の範囲を超える変更については、 EZDOCで提供する文書用の次のスタイルシートezdocCore.xslの中で定義されている XSLTのテンプレートの内、必要なものを個別のスタイルシートに複写して、 これを修正すれば、こちらが優先して適用されるので、変更が可能です。

  例えば、 次の内容をezdoc.xslに追加すると文書の最後の「以上」の出力を止めることができます。
<template name="ijyo">
</template>

  しかし、一般的には簡易な変更の範囲を越える変更については、 HTML、XSLTの知識を必要とし、本書の範囲をこえるので詳細は省略します。 市販の参考書などが多数ありますので、これらを参考にして下さい。

4.5 文書ファイルの変換とエラーメッセージ

  EZDOCを使用する上では、バッチファイルの外、 次の3つのファイルを修正する可能性があります。
1)ezdoc.xml、 2)ezdoc.xsl、 3)ezdoc-files.xml
これらのファイルに関して、 誤った修正をしてバッチファイルで変換処理をした時に表示される エラーメッセージの例を 「付録(3) エラーメッセージと対処」にまとめてあります。 これを参考に各ファイルを修正して下さい。

  IEで文書ファイルを直接表示している場合は、 文書の体裁が崩れて文字列だけが抽出されて これらが羅列して表示されます。 この場合には、 一度バッチファイルを実行すると上の何れかのエラーが表示されるので、 これを参考に誤りを修正します。

5 文書印刷の書式

  EZDOCで生成したHTMLを印刷する時は、ブラウザを使います。 この時、ブラウザのページ設定を調整すると整った形で文書を印刷できます。 IEの場合のページ設定の設定項目と著者が主に使用している値を次に示します。 調節には、IEで、[ファイル]-[ページ設定]でページ設定ウィンドウを開きます。

 
# 項目 推奨値 備考
1) 用紙サイズ A4
2) 印刷の向き
3) ヘッダー (なし)
4) フッター &b&p/&P&b ページ番号(例: 2/5)
5) 左余白 25 (mm)
6) 右余白 17 (mm)
7) 上余白 20 (mm)
8) 下余白 15 (mm)

以上


付録(1) 文書の枠組みを記述する要素

  文書ファイルに記述する要素の内、文書の体裁の大枠を決める要素を次に示します。
# 要素名 属性 子要素 説明
1) article 文書ファイルのルート要素。

title

subtitle

date

author

preface

section

appendix

pa
2) article/title 文書の表題。

(文字列)
3) subtitle 副表題。

(文字列)
4) date 日付。

(文字列)
5) author 著者名。
6) width 著者名と日付の記述幅。 単位はピクセル。

br 「付録(2) 段落の中を記述する要素」を参照。

(文字列)
7) preface 前書き。

pa
8) section 章、節、項などの親要素。

ref-id 番号等参照に向けた識別子の定義。 内容が他の定義と重複しないことが必要。

title

section

pa
9) section/title 章、節、もしくは項などの標題。

(文字列)
10) appendix 付録の親要素。

ref-id 番号等参照に向けた識別子の定義。 内容が他の定義と重複しないことが必要。

title

pa
11) appendix/title 付録の標題。

(文字列)
12) pa 段落の親要素。

a (これらの子要素と文字列を合わせて"TypeA"とします。 これらの要素については、 「付録(2) 段落の中を記述する要素」を参照して下さい。)

blockquote

br

center

dl

dl-n

fig

img

ol

photo

pre

ref

small

table

ul
(注) (文字列) 内容を文字列で記述します。
(TypeA) 詳細については「付録(2) 段落の中を記述する要素」を参照して下さい。

付録(2) 段落の中を記述する要素

  段落の中に書いて、段落の中を記述する要素(TypeA)を次に示します。

 
# 要素名 属性 子要素 説明
1) a リンク先を設定。
href リンク先のURL。
target 表示先のフレームないしウィンドウの名。
img 画像によるリンク。
(文字列) 文字列によるリンク。
2) blockquote 引用。
(TypeA)
3) br 改行。常に空要素。
4) clear 画像に対する文字列の回りこみを解除(clear="all")。
5) caption 表の題。
(文字列)
6) center 中央に配置。
(TypeA)
7) dd 定義リストにおける用語の説明。
(TypeA)
8) dl 定義リスト。
dd
dt
9) dl-n 番号付き定義リスト。
dd
dt
10) dt 定義リストで定義する用語。
(文字列)
11) fig 図の表示。
height 高さ。単位はピクセル。
ref-id 番号等参照に向けた識別子の定義。 内容が他の定義と重複しないことが必要。
src 参照するファイル名。
width 幅。単位はピクセル。
title
12) fig/title 図の標題。
(文字列)
14) img 画像の表示。常に空要素。
align 画像に対する文字列の回りこみを可とする時の画像の置場所 {left | right}。
height 高さ。単位はピクセル。
src 参照するファイル名。
width 幅。単位はピクセル。
15) li 箇条書きの項目。
(TypeA)
16) ol 番号付き箇条書き。
li
17) photo 写真の表示。
height 高さ。単位はピクセル。
ref-id 番号等参照に向けた識別子の定義。 内容が他の定義と重複しないことが必要。
src 参照するファイル名。
width 幅。単位はピクセル。
title
18) photo/title 写真の標題。
(文字列)
20) pre 整形済みテキスト。
(文字列)
21) ref 図表などの番号と表題の参照。
ref-id 参照する番号等の定義における識別子。
swTitle 表題の表示/非表示{on|off}。
22) small 文字列を小さく表示する。
(文字列)
23) table 表の定義。
border 枠線の太さ。枠線なしもしくは枠線の太さ1{0|1}。
ref-id 番号等参照に向けた識別子の定義。 内容が他の定義と重複しないことが必要。
width 表の幅。単位は、ピクセルもしくは割合。
caption
tr
tr-nc
24) td 表のデータ。
align 横位置 {left | center | right}。
colspan 横方向のセルの結合。
rowspan 縦方向のセルの結合。
valign 縦位置 {top | middle | bottom}。
width セルの幅。単位は、ピクセルもしくは割合。
(q-n) 内容が"q-n"もしくはこれから始まる時、 要素"tr"が開始タグ"table"から出現した数をかぞえ、 "q-n"をこの値に置き換えます。
(TypeA)
25) th 表の列の題。
align 横位置 {left | center | right}。
colspan 横方向のセルの結合。
rowspan 縦方向のセルの結合。
valign 縦位置 {top | middle | bottom | baseline}。
width セルの幅。単位は、ピクセルもしくは割合。
br
(文字列)
26) tr テーブルの行の親要素。
align 以下のtdのデフォルト。 横位置 {left | center | right}。
valign 以下のtdのデフォルト。 縦位置 {top | middle | bottom | baseline}。
th
td
27) tr-nc 行番号として数えないテーブルの行の親要素。
align 子要素"th"ないし"td"のデフォルト。 横位置 {left | center | right}。
valign 子要素"th"ないし"td"のデフォルト。 縦位置 {top | middle | bottom | baseline}。
th
td
28) ul 番号無しの箇条書き。
li
(注) (文字列) 文字列

付録(3) エラーメッセージと対処

  EZDOCで表示されるエラーメッセージの例を示します。

  1) 文書ファイルの誤り

  誤りのある文書ファイルをバッチファイルでHTMLに変換しようとすると 次のようなメッセージが表示されます。
D:\exercise>echo off
ezdoc.bat (ezdoc.bat Version 7.3)
HTMLへ変換します

Error occurred while parsing document.

Code:   0xc00ce56d
URL:    file:///D:/exercise/ezdoc.xml
Line:   31
Column: 3
End tag 'setion' does not match the start tag 'section'.
続行するには何かキーを押してください . . .
この例では、 エラーメッセージによると、"ezdoc.xml"ファイルの31行目の 終了タグ'setion'が開始タグ'section'と一致しないのが原因との指摘で、 スペルミスが分かるので、これを修正します。

  2) スタイルシートファイルの誤り

  文書の体裁の変更において個別のスタイルシートの修正を誤った状態でバッチ処理で HTMLへ変換しようとした時の例です。
D:\exercise>echo off
ezdoc.bat (ezdoc.bat Version 7.3)
HTMLへ変換します

Error occurred while parsing document.

Code:   0xc00ce01d
URL:    file:///D:/exercise/ezdoc.xsl
Line:   16
Column: 50
Reference to undeclared namespace prefix: 'xl'.
続行するには何かキーを押してください . . .
上のエラーメッセージからは、 修正したスタイルシートファイル"ezdoc.xsl"の16行目の接頭辞(prefix) 'xl'が誤りと指摘されてるので、そこを直して再度変換処理をします。

  3) ファイル一覧の誤り

  バッチ処理によって複数の文書ファイルを統合してHTMLへ変換しようとして、 統合用ファイル"ezdoc-files.xml"に記述するファイル名を間違って記入した時には、 次のようなエラーが表示されます。
D:\exercise>echo off
ezdoc.bat (ezdoc.bat Version 7.3)
複数の文書ファイルを統合します

Error occurred while executing stylesheet '..\creaTool\ezdoc\tool\\mkezdoc-integ
.xsl'.

Code:   0x800c0006
指定されたオブジェクトは見つかりません。
続行するには何かキーを押してください . . .
ファイル名に 「複数の文書ファイルを統合」の後に「指定されたオブジェクトは見つかりません」と 表示されているので、文書ファイル名の誤りと考えます。 ファイル名を修正して再度バッチで変換を続けます。

付録(4) EZDOC のインストールとアンインストール

  ここではEZDOCのインストールとアンインストールについて説明します。 EZDOCをインストールして使用するにはXSLTプロセッサmsxsl.exeのインストールが併せて必要です。
1) インストール
インストールは次の手順によります。
a) インストールで使用するファイル ezdoc-73.zip を ホームページ「ソフトの道具箱」(URL:http://toolbox-crea.cool.coocan.jp/) からのダウンロードして入手します。
b) インストールする基盤フォルダを決め、 その直下にフォルダ creaTool が無ければ、これを作ります。
c) そして、ファイル ezdoc-73.zip の内容をフォルダ creaTool の下に解凍して下さい。

フォルダ ezdoc-73 が生成され、そこに中身が展開されたら完了です。 フォルダ構造は次のようになります。
(基盤フォルダ)
   +--creaTool
        +--ezdoc-73
この場合、"(基盤フォルダ)/creaTool/ezdoc-73"がEZDOCのホームフォルダになります。

2) アンインストール
インストールした EZDOC ホームフォルダを配下のファイルごと削除して終わりです。

付録(5) XSLTプロセッサのインストールとアンインストール

  EZDOCでは、XSLTプロセッサとしてmsxsl.exeを使用します。 msxsl.exeは、Microsoft社が無償で提供しています。
1) インストール
a) 下の URL を右クリックし、新しいウィンドウで開くを選択
"http://www.microsoft.com/downloads/Search.aspx?displaylang=en"
b) ページの最初の行の虫眼鏡をクリックし、 生成された検索用のボックスに"msxsl.exe"を入力して改行。
c) 表示された"Command Line Transformation Utility (msxsl.exe)"をクリック。
d) msxsl.exe ページの Download ボタンをクリック。
e) ダウンロードした msxsl.exe をパスの通ったフォルダにコピーするか、 もしくは任意のフォルダに置いてパスを設定します (パスの設定の仕方は、必要なら下を参考にして下さい)。

[パスの設定]
Windows7の場合は個別のユーザ毎に次のように行います。
a) 次の順にリンクないしボタンなどをクリックして進みます。
[コントロールパネル]−[システム]−[詳細設定]−[環境変数]
b) ユーザ環境変数側で次の処理をします。
i) 環境変数"PATH"の設定が無ければ、新規ボタンをクリックします。
i) 変数名に"path"を記入。
ii) 変数値にmsxsl.exeを置いたフォルダのパスを記入 (例: D:\usr\bin)。
ii) 環境変数"PATH"の設定があれば、"PATH"の行をクリックして 編集ボタンをクリックします。
i) 変数値の最後に";"を追加して記入。
ii) 変数値の最後にmsxsl.exeを置いたフォルダのパスを追加して記入 (例: D:\usr\bin)。
c) その後、OKボタンを3回続けクリックします。
2) アンインストール
パスの通った所に置いたmsxsl.exeを削除して終わりです。