平成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 に変換してブラウザに 表示するようにします。 |
2 概要
2.1 機能
EZDOC では、文書ファイルをHTMLに変換しますが、 HTMLといってもいわゆるWebのページ作りが目的ではなく、 ワープロで作るような文書を作ります。 本マニュアルが一つの例です。 EZDOC では、1ページの簡単な文書から、 小規模なソフトウェアのマニュアル程度の規模の文書を作ることを目標としています。 |
EZDOCは、次の機能と特長を持ちます。
|
本書の説明では、XML に関連する内容が含まれています。 XML になじみのない方は、 ホームページ「ソフトの道具箱」に 掲載している「 XML文書について」に 本ソフトを使う上で必要な程度の簡単な説明がありますので一読して下さい。 |
2.2 動作環境
EZDOCについては、次の環境で動作を確認しています。
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 テンプレートの表示」を見て下さい。 これは、文書ファイルのテンプレートとして EZDOCが用意する文書ファイルをそのままHTMLに変換して表示したものです。 |
それでは、思いどおりに文書を作る第一歩として、 「図3.1」の 「最初の段落の内容」の部分を「Hello, world!」と変えた文書を作ってみましょう。 |
まず最初に、基盤フォルダの下に適当な名前を付けて
作業用のフォルダを作ります。
そのフォルダの下に EZDOC ホームフォルダから
"ezdoc.bat"を複写し、ダブルクリックして実行して下さい(注)。
(注) バッチファイルを実行すると「MS-DOSの窓」が開いて最後の行に、 「続行するには何かキーを押してください . . .」が表示されます。 この窓にはバッチファイルによる処理内容などが表示されます。 通常は、適当なキーを押して下さい。窓が閉じます。 |
バッチファイルの最初の実行では次の3つのファイルが
バッチファイルと同じフォルダに生成されます。
ここで確認のため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の最初の2行が、 XML文書としての宣言です。 第1行目は、このファイルがXML文書であることを示していて、 さらにこのファイルで使用している文字コードを定義します。 第2行目は、 このファイルを直接ブラウザで表示する時に適用するスタイルシートを定義します。 文書ファイルを直接ブラウザで表示することがなく、 後で説明する変換後のHTMLを表示するだけなら、第2行目は不要です。 |
XML宣言における文字コードの指定では、次のような表記が使えます。 |
|
そして第3行目から最後までが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.4.1 リンク(a)
Webのページやパソコン内の他の文書へのリンクを書くことができます。 他文書へのリンクを書くときのフォルダの区切りは、"\"も使えますが、 他との整合性を考慮し EZDOC では"/"を使うことを推奨します。 |
[書き方の例]
|
[表示] |
3.4.2 引用(blockquote)
他の文書から引用した文章などを書きます。引用を示すために、 要素 blockquote の外側の文章に対して、一段下げて内容を表示します。 |
[書き方の例]
|
[表示] |
3.4.3 改行(br)
文章の途中で改行するためには、空の要素 br を書きます。 書き方の例にもあるように、テキストエディタの改行は、 HTMLへの変換の段階で無視、もしくは空白1文字に置き換えられます。 |
[書き方の例]
[表示] |
3.4.4 中央揃え(center)
文字列や図表などを中央に配置して表示します。 |
[書き方の例]
|
[表示] |
3.4.5 定義リスト(dl/dt/dd)
用語などの定義には、定義リストの親要素 dl と子要素 dt と dd を使います。 要素 dt に定義する用語を、そしてその説明を要素 dd に書きます。 |
[書き方の例]
|
[表示] |
3.4.6 画像表示(img)
要素 img を使って画像を表示することができます。常に空要素です。 実際の文書の作成に当たっては、 別途規定する図の要素 fig や写真の要素 photo を使う方が便利でしょう。 これらについては、次節で説明しています。 |
[書き方の例]
|
[表示] |
3.4.7 整形済みテキストの表示(pre)
テキストエディタで書いたとおりに表示します。 プログラムソースなどを書く時に使います。 要素 pre の中の文字は、通常の文章に比べ一段階小さく表示されます。 XMLの構文を書くときには、pre 要素の中でさらに "<![CDATA[" と "]]>" で表示する内容を囲います。 |
[書き方の例]
|
[表示] |
3.4.8 小さく表示(small)
一部の文字列を小さく表示する時に使います。 |
[書き方の例]
|
[表示] |
3.4.9 表(table/caption/tr/th/td)
表は、要素"table"を使って書きます。 表に標題を付ける時は、要素"caption"に書きます。 表には、行(レコード、親要素"tr")を複数書くことができ、 要素"tr"にはさらに表題の要素"th"、 もしくはデータの要素"td"を各々複数書くことができます。 |
1)表の基本的な書き方 |
[書き方の例]
|
[表示] [tdの属性] |
2)align/valignの例 |
[書き方の例]
|
[表示] |
3)colspan/rowspanの例 |
[書き方の例]
|
[表示] |
3.4.10 箇条書き(ul/ol/li)
箇条書きには、先頭に"・"を付けて表示する番号なしと、 先頭に番号をつけた番号付きがあります。 番号なしの場合は親要素"ul"、番号付きの場合は、親要素"ol"を使います。 どちらの場合も、箇条書きの個別の項目を子要素"li"に書きます。 要素"ul"の書き方から示します。 |
[書き方の例]
|
[表示] |
番号付きの場合は、要素"ul"の代えて要素"ol"要素を使い、
要素"li"の使い方は同じです。
番号付き箇条書きの項目の中に再度番号付き箇条書きを書いた場合は、
内側の番号が、a)、b)... のように変わります。
番号付きの表示は、次のようになります。
[表示] |
3.5 段落の中を記述する要素(その2)
ここでは、段落の中を記述する残りの要素などについて説明します。 |
|
3.5.1 番号付き定義リスト(dl-n)
定義する用語の前に番号を付ける定義リストです。 番号を付ける時は、定義リストの要素"dl"に代えて"dl-n"を使用し、 その他の要素"dt"と"dd"は定義リスト"dl"の場合と同じです。 |
[書き方の例]
[表示] |
3.5.2 標題付き図(fig)
標題を付けた図を表示します。標題は、子要素"title"に書きます。 |
[書き方の例]
|
[表示] |
[figの属性]
|
3.5.3 写真(photo)
標題を付けた写真を表示します。標題は、子要素titleに書きます。 |
[書き方の例]
|
[表示] |
[photoの属性]
|
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"と同じです。 |
[書き方の例]
|
[表示] |
3.5.5 図表などへの番号付けとその参照 (属性"ref-id"と要素"ref")
EZDOCでは、章、節、...と付録には、常に自動的に番号を付けますが、
その他の要素にも番号を自動的に付け、
さらにそれらの番号と標題を文章の中で参照して表示することができます。
自動的に番号を付けることができる要素を次の表にまとめます。
番号は、次表の要素に属性 ref-id を付加するだけで表示されるようになります。
属性 ref-id には、参照する時の識別子として、適当な文字列を書きます。 ただ、文書の中の番号付けにおいて他の識別子と重複しないようにすることが必要です。 |
番号付けの例として、写真に番号を付ける例を次に示します。 |
[書き方の例]
|
[表示] |
本文中でこれら図表等の番号や標題について記述する時、 図表等に付いた番号や標題と本文に食い違いが生じないよう、 図表等を参照する要素"ref"を使うと便利です。 要素"ref"は次のように使います。 |
[書き方の例]
|
[表示] |
[refの属性]
|
定義されていない"ref-id"を書いた場合は参照した個所に次のように表示されます。
REF:"適当な文字列です"図や表の番号は、これまでの例では章番号とその中の通し番号で構成されていますが、 文書の中での通し番号とすることができます。 変更の仕方については、「4.4 文書の体裁の変更」で説明します。 |
図、写真、および表に関して、これらを前書きや付録に置く場合、 もしくは章を持たない文書などで章の外に置く場合で、 これらに番号を付ける時は、 デフォルトのままでは番号付けが正しく機能しません。 この場合は、文書の中での通し番号に変更する必要があります。 |
3.6 文書ファイルを書きやすくする工夫
実はXMLに準拠した文書ファイルは、教科書どおりに書くと、
インデントが深くなったり、
内容がタグにはさまれていて修正する時に骨が折れたりします。
これらは、少しの工夫で大幅に改善できます。
XMLの特性を踏まえることがポイントです。
著者は、次のような点を実践してストレスを減らして書いています。
|
4 バッチファイルによるHTMLへの変換
EZDOC においては、「3.1 文書ファイルの使い方と内容」等で説明してきたように、 基本はEZDOCホームから複写しただけのバッチファイルを実行してHTMLを生成しますが、 この他、目次を付けたHTMLとしたり、 文書の量が多い時など複数の文書ファイルを作ってこれらを統合して HTMLを生成したりすることができます。 |
パラメータによって変りますが、
バッチファイルの実行によって生成されるファイルを次に示します。
こららは、全てバッチファイルが実効された作業フォルダに生成されます。
必須の欄に○印があるファイルは、必ず存在し使用されます。 |
この後、HTMLの生成において調整が可能な次の内容について説明します。
また、これらと合わせて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)の構成は次のようになります。
複数文書ファイルの統合と目次の生成は同時に指定することが可能です。 |
4.4 文書の体裁の変更
EZDOCでは、文書の体裁を共通のスタイルシートで定義していますが、
個別に文書の体裁を変えることができます。
この体裁の変更に関して、次の3つの変更はEZDOCで簡便な方法を用意しています。
個別に文書の体裁を変更するには、 文書ファイルと同じフォルダにあってこれにに対応しているスタイルシートを テキストエディタで開き、変更内容に応じて次に示すように修正します。 その後内容を保存してバッチファイルを実行すると、 体裁を変えたHTMLを生成することができます。 |
1)書体(フォント)を明朝体へ変更 |
明朝体への書体の変更は、"ezdoc.xsl"の次の3行の内、
中央の行をコメントにならない部分に複写します。
|
次のように変更するのが簡単です。
|
2)フォントサイズの変更 |
書体を小さくする場合も、同様です。次の中央の行を
コメントとならない部分に複写します。
なお、この指定は文書全般に作用するので部分的に小さくする場合は要素 small を使います。
|
3)図番などを文書内の一連の番号に変更 |
図番などは、デフォルトでは章の中での通し番号になっていますが、
これを文書内での一連の番号に変更することができます。
この場合は次の中央の行をコメントでないようにします。
|
また、上で述べた簡易な変更の範囲を超える変更については、 EZDOCで提供する文書用の次のスタイルシートezdocCore.xslの中で定義されている XSLTのテンプレートの内、必要なものを個別のスタイルシートに複写して、 これを修正すれば、こちらが優先して適用されるので、変更が可能です。 |
例えば、
次の内容をezdoc.xslに追加すると文書の最後の「以上」の出力を止めることができます。
|
しかし、一般的には簡易な変更の範囲を越える変更については、 HTML、XSLTの知識を必要とし、本書の範囲をこえるので詳細は省略します。 市販の参考書などが多数ありますので、これらを参考にして下さい。 |
4.5 文書ファイルの変換とエラーメッセージ
EZDOCを使用する上では、バッチファイルの外、
次の3つのファイルを修正する可能性があります。
1)ezdoc.xml、 2)ezdoc.xsl、 3)ezdoc-files.xmlこれらのファイルに関して、 誤った修正をしてバッチファイルで変換処理をした時に表示される エラーメッセージの例を 「付録(3) エラーメッセージと対処」にまとめてあります。 これを参考に各ファイルを修正して下さい。 |
IEで文書ファイルを直接表示している場合は、 文書の体裁が崩れて文字列だけが抽出されて これらが羅列して表示されます。 この場合には、 一度バッチファイルを実行すると上の何れかのエラーが表示されるので、 これを参考に誤りを修正します。 |
5 文書印刷の書式
EZDOCで生成したHTMLを印刷する時は、ブラウザを使います。 この時、ブラウザのページ設定を調整すると整った形で文書を印刷できます。 IEの場合のページ設定の設定項目と著者が主に使用している値を次に示します。 調節には、IEで、[ファイル]-[ページ設定]でページ設定ウィンドウを開きます。 |
|
以上 |
付録(1) 文書の枠組みを記述する要素
文書ファイルに記述する要素の内、文書の体裁の大枠を決める要素を次に示します。
|
付録(2) 段落の中を記述する要素
段落の中に書いて、段落の中を記述する要素(TypeA)を次に示します。 |
|
付録(3) エラーメッセージと対処
EZDOCで表示されるエラーメッセージの例を示します。 |
1) 文書ファイルの誤り |
誤りのある文書ファイルをバッチファイルでHTMLに変換しようとすると
次のようなメッセージが表示されます。
|
2) スタイルシートファイルの誤り |
文書の体裁の変更において個別のスタイルシートの修正を誤った状態でバッチ処理で
HTMLへ変換しようとした時の例です。
|
3) ファイル一覧の誤り |
バッチ処理によって複数の文書ファイルを統合してHTMLへ変換しようとして、
統合用ファイル"ezdoc-files.xml"に記述するファイル名を間違って記入した時には、
次のようなエラーが表示されます。
|
付録(4) EZDOC のインストールとアンインストール
ここではEZDOCのインストールとアンインストールについて説明します。
EZDOCをインストールして使用するにはXSLTプロセッサmsxsl.exeのインストールが併せて必要です。
|
付録(5) XSLTプロセッサのインストールとアンインストール
EZDOCでは、XSLTプロセッサとしてmsxsl.exeを使用します。
msxsl.exeは、Microsoft社が無償で提供しています。
|