DITAソースを書いてみよう!

実際に日本語DITAソースを書き、DITA-OTを使って、PDF化に挑戦してみましょう。(2013年2月1日公開)

DITAソースを書く前に

前回は、DDITA-OT付属のサンプルDITAファイルを一部日本語にして、PDF、XHTML、TOCJS(XHTML+JavaScrip)、HTMLHELPに変換しました。

今回は、新規に日本語のDITAソースを書いてPDFにしてみます。

DITAは、マップ(map)ファイルが一つと、トピック(topic)ファイルが複数集まったソースです。 まずトピックを作りましょう。 汎用トピックを頂点として、機能を制限したタイプとしてconceptとtask、reference、glosarryがあります。 もちろん、自分で特殊化を行えば様々なタイプを作ることが出来ますし、実際、学習関係とかいろいろなタイプが出てきています。 特殊化を行うには十分な知識と工数が掛かりますので、ここでは取り扱いません。

さて、皆さんはどのタイプを使えばよいのでしょうか?
  • 一般的に、概要・概念などを記述する場合はconceptタイプ
  • 手順などの段階的な事項を扱う場合はtaskタイプ
  • 参照、ライブラリィ、用語集などにはreference、glosarrタイプ
というふうに推奨されています。

ここでは、第一回目の「まず変換してみよう!」のページの一部をDITA化してみましょう。 どのタイプでしょうか・・・ そうです。上記タイプで言えば、conceptタイプとtaskタイプの両方ですね。 前半がconceptタイプ、後半がtaskタイプになるでしょう。 そして、取りまとめるマップと呼ばれる目次のようなものを作る必要があります。

今回は、まず前半のconceptタイプを作って、うまくPDF変換が出来るかを試してみましょう。 今回もインストール済みのDITA-OT1.7.M4を使います。 注)1/2に安定版がリリースされましたが、1/14にDITA-OT1.7.1、1/28にDITA-OT1.7.2がリリースされています。。 DITA-OTは使い勝手が良くなるように、常に進化しているのですが。。。もう少し落ち着くまで、DITA-OT1.7.M4を使います。

DITAソースを書いてみよう1(conceptタイプのトピックを作ってみる)

まずは、第一回目の「まず変換してみよう!」のページのどこまでを1トピックにするか決めます。 手順が始まる『実際に変換してみる』の前までが、conceptタイプのトピックになりますが、ここでは、『DITA-OT Open Toolkitのインストール』の前でも切って二つのトピックにします。

conceptタイプのトピックを作るにあたってはお決まりのパターンがあります。 UTF-8文字コードが使えるエディタで、次のように記述してみましょう。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="ユニークなID(ファイル名で良い)" xml:lang="ja-jp">
 <title>タイトルを入れる</title>
 <shortdesc></shortdesc>
 <conbody>
  <p>本文です。</p>
 </conbody>
</concept>
  • m1-1.ditaファイル
    さて、準備が整ったところで、実際に『DITA-OT Open Toolkitのインストール』の前までを記述していきます。 ファイル名をm1-1.dita、タイトルを「ドキュメント制作の構造化手法」、各段落を<p>タグで囲みます。 ブラウザからテキストをコピーして、タグ等を付加してください。、次のようになりましたか。 注)ファイル名(m1-1.dita)の先頭文字に数字や特殊文字を使わないでください。「文字」か「_」を使用します。
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="m1-1" xml:lang="ja-jp">
     <title>ドキュメント制作の構造化手法</title>
     <shortdesc></shortdesc>
     <conbody>
    <p>ドキュメントを効率よく制作・メンテし、多言語対応も簡単に出来る手法として、世界ではDITAというXMLを使った構造化言語が技術マニュアルを中心に使われています。
    </p><p>特に、構造化に適した技術文書を軸に欧米ではかなり広まっています。しかし、日本では、技術文書と言えどもレイアウトデザインや、冗長な言葉使いが壁となって、なかなか広まっていない現実があります。
    </p><p>私たちは、ワンソースマルチユースという一つのソースから、複数の出力(PDF、XHTML、CHM等のヘルプ形式、EPUB)が出来るDITAソースをDITA-OT(DITA-OT Open Toolkit)というフリーな変換システムを使って実践してみます。
    </p><p>まずは・・・どんな出力が出来るかを実際にDITA-OTを使って、試してみましょう。
    </p>
     </conbody>
    </concept>
さぁ、PDF変換してみましょう。m1-1.ditaファイルがC:\Magicalフォルダにあるとします。
java -jar lib/dost.jar /i:C:\Magical\m1-1.dita /transtype:pdf /outdir:C:\Magical\out

いかがでしょうか?

C:\Magical\outフォルダに、m1-1.dita.pdfファイルが出来ているでしょうか。

 m1-1.dita出力サンプル.pdf

DITAソースを書いてみよう2(6個のタグを追加する)

続いて残りの『DITA-OT Open Toolkitのインストール』から、『実際に変換してみる』の前までを同じように作ります。

  • m1-2.ditaファイル
    ファイル名をm1-2.dita、タイトルを「DITA-OT Open Toolkitのインストール」にします。 ここでは、見栄えを少し良くするためもあり、更に次の6個のタグを追加します。
    • <filepath></filepath>:URLなどのファイルパスに使用します。
    • <uicontrol></uicontrol>:[ ]で括られた単語に使用します。
    • <menucascade></menucascade>:[ ]-[ ]と連続した場合、一番外側に使用します。その際、間のハイフン(-)は削除します。
    • <codeph></codeph>:「 」で括られた単語に使用します。
    • <ul></ul>:中黒(・)を使用している文章全体の一番外側に使用します。
    • <li></li>:中黒(・)を使用している各文章に使用します。
    出来上がりは次のようになります。
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="m1-2" xml:lang="ja-jp">
     <title>DITA-OT Open Toolkitのインストール</title>
     <shortdesc></shortdesc>
     <conbody>
    <p>まずは、核となるDITA-OT Open Toolkitをインストールします。
    </p><p>ダウンロードサイトは次のURLです。
    </p><p><filepath>http://sourceforge.net/projects/dita-ot/files/</filepath>
    </p><p>ここで迷うのは、どのバージョンを使用するか?です。
    </p><p>すぐに、DITAを業務で使うなら、一番安定していると思われるDITA-OT1.5.4の安定版をお勧めします。
    </p><p>上記サイトから、<uicontrol>[DITA-OT Stable Release]</uicontrol>をクリックし、次に<uicontrol>[DITA Open Toolkit 1.5.4]</uicontrol>をクリック、全部が入った<uicontrol>[DITA-OT1.5.4_full_easy_install_bin.zip]</uicontrol>をダウンロードすると良いでしょう。
    </p><p>今回は、実験として使いますので、11/26のDITA OT 1.7.M4最新版で開発中のものを使ってみます。
    </p><p>上記サイトから、<menucascade><uicontrol>[DITA-OT Latest Test Build]</uicontrol><uicontrol>[DITA OT 1.7.M4]</uicontrol><uicontrol>[DITA-OT1.7.M4_full_easy_install_bin.zip]</uicontrol></menucascade>をダウンロードします。
    </p><p>解凍して出来たフォルダ<codeph>「DITA-OT1.7.M4」</codeph>をルート直下で使います。
    </p><p>まず、ドキュメントを見ましょう。
    </p><p><filepath>C:\DITA-OT1.7.M4\doc\userguide.pdf</filepath>を開きます。
    </p><p>これと同じものが、インターネット上でも見れます。
    </p><p><filepath>http://dita-ot.sourceforge.net/dev/</filepath>
    </p><p>開発中ですので、バージョンM4ですが、ドキュメントはまだ<codeph>「M2」</codeph>ですね。
    </p><p>すぐに、サンプルDITAファイルを使ってPDF化したいところですが、待ってください。他にも環境設定が必要です。
    </p><p>ちなみに、<codeph>「full_easy_install」</codeph>パッケージにより次のライブラリーがすでに無償でインストールされています。
    </p>
    <ul><li>Apache Ant, version 1.8.4
    </li><li>Apache Catalog Resolver, version 1.1
    </li><li>Apache Commons Codec, version 1.4
    </li><li>Apache FOP, version 1.0
    </li><li>ICU for Java, version 49.1
    </li><li>Apache Xerces, version 2.11.0
    </li><li>Saxon, version 9.1
    </li></ul>
    <p>変換するのに必要な他のライブラリーはJAVAです。
    </p><p>下記サイトからダウンロードして、インストールしてください。
    </p>
    <ul><li>JRE or JDK, version 6 or later
     <p><filepath>http://www.oracle.com/technetwork/java/javase/overview/index.html</filepath>
     </p><p>JDK (Java Development Kit)のインストールを推奨します。
     </p>
    </li></ul>
     <p>HTMLヘルプを生成するのであれば、合わせて次のものもインストールしておいてください。
     </p>
    <ul><li>Microsoftヘルプワークショップ
     <p><filepath>http://msdn.microsoft.com/en-us/library/windows/desktop/ms669985%28v=vs.85%29.aspx</filepath>
     </p>
    </li></ul>
    <p>これで、準備完了です。
    </p>
     </conbody>
    </concept>
さぁ、PDF変換してみましょう。m1-2.ditaファイルがC:\Magicalフォルダにあるとします。
java -jar lib/dost.jar /i:C:\Magical\m1-2.dita /transtype:pdf /outdir:C:\Magical\out

C:\Magical\outフォルダに、m1-2.dita.pdfファイルが出来ているでしょうか。 m1-2.dita出力サンプル.pdf

次回は、この二つのトピックを使って、1ファイルのPDF出力となるようにマップ(map)を作ってみます。

ご意見・ご質問等があれば、お気軽にお尋ねください。

関連トピック

Powered by x-magic

© 2014 まじかるテクノロジー有限会社 All Rights Reserved. / Transformed by x-magic plugin for DITA Open Toolkit at 2015-04-25T13:35:33.425+09:00