文書遊戯

Eliot Kimberさんの書いた"DITA for Practitioners Volume 1"を読みながら、DITAの理解を深める努力をしています。"DITA for Practitioners"はVol 1、Vol 2から成り、今のところVol 1のみが刊行されています。英文書籍ですが、Amazon.co.jpで購入できます。値段は現在(2012.5.27)、3,170円です。私が買ったときは3,230円だったので、少し円高になったのかな。

Vol1では、DITA文書を一から書いてみるチュートリアルのために、1/3くらいのページが割かれています。対象の文書は、日本の合気道をテーマにした簡単な文書ですが、マップとトピックの一通りの書き方を経験できる、よく練られた文書になっています。マークアップはDITA1.2に準拠しています。Vol 2では特殊化やDITA-OTのカスタマイズについて書かれるそうなので、Vol 2の完成を楽しみにしています。

私は以前DITA1.1のライティングガイドを書いたことがありますが、この本を読んで、DITA1.1→DITA1.2でライティングの作法がいくつか変わっていることを学びました。ライティングガイドを改版するときに修正が必要です。

navtitle属性(DITA1.1)

DITA1.1→DITA1.2で変わったライティングの作法の一つがnavtitle属性です。DITA1.1ライティングガイドの中の「トピック参照を書く<topicref>」の箇所に、私は以下のように書きました。

ナビゲーション・タイトルの指定(navtitle属性)

参照先のトピックまたはマップのタイトルを指定します。ナビゲーション・タイトルの指定は必須ではありませんが、マップを見ただけで参照先のトピックが分かるようにするため、常にナビゲーション・タイトルを指定することを推奨します。

このガイドに従って書いたマップの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN"
"http://docs.oasis-open.org/dita/v1.1/OS/dtd/bookmap.dtd">
<bookmap id="dita_ot_tips" xml:lang="ja-jp">
  <title>DITA Open Toolkit活用ガイド</title>
  <bookmeta>
    <prodinfo>
      <prodname>DITA Open Toolkit活用ガイド</prodname>
      <vrmlist>
        <vrm version="00E"/>
      </vrmlist>
    </prodinfo>
  </bookmeta>
  <frontmatter>
    <topicref navtitle="権利について" type="concept" href="regal_notice.dita"/>
    <booklists>
      <toc/>
    </booklists>
  </frontmatter>
  <chapter format="ditamap" href="about_dita_ot/about_dita_ot.ditamap"
    navtitle="DITA Open Toolkitとは"/>
  <chapter format="ditamap" href="dita_ot_installation/dita_ot_installation.ditamap"
    navtitle="DITA Open Toolkitのインストール"/>
  <chapter collection-type="sequence" format="ditamap" href="jp_pdf_setup/jp_pdf_setup.ditamap"
    navtitle="PDF出力（FOプラグイン）の日本語化"/>
  <chapter format="ditamap" href="dita_ot_execution/dita_ot_execution.ditamap"
    navtitle="DITA Open Toolkitの実行方法" type="concept"/>
  <chapter collection-type="unordered" format="ditamap" href="pdf_customize/pdf_customize.ditamap"
    navtitle="PDF出力のカスタマイズ"/>
  <chapter collection-type="unordered" format="ditamap" href="html_customize/html_customize.ditamap"
    navtitle="XHTML/HTML Help出力のカスタマイズ"/>
  <backmatter>
    <booklists>
      <indexlist/>
    </booklists>
  </backmatter>
</bookmap>

navtitle要素(DITA1.2)

DITA1.2ではnavtitle属性の使用は非推奨に変わっています。代わりnavtitle要素を使います。navtitle属性で書くときより、ちょっとタグの構造が深くなるのですが、topicref→topicmeta→navtitleという構造でトピックのタイトルを書きます。上記のマップをDITA1.2準拠に書き換えると下記のようになります。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap id="dita_ot_tips" xml:lang="ja-jp">
    <title>DITA Open Toolkit活用ガイド</title>
    <bookmeta>
        <prodinfo>
            <prodname>DITA Open Toolkit活用ガイド</prodname>
            <vrmlist>
                <vrm version="00E"/>
            </vrmlist>
        </prodinfo>
    </bookmeta>
    <frontmatter>
        <topicref type="concept" href="regal_notice.dita">
            <topicmeta>
                <navtitle>権利について</navtitle>
            </topicmeta>
        </topicref>
        <booklists>
            <toc/>
        </booklists>
    </frontmatter>
    <chapter format="ditamap" href="about_dita_ot/about_dita_ot.ditamap">
        <topicmeta>
            <navtitle>DITA Open Toolkitとは</navtitle>
        </topicmeta>
    </chapter>
    <chapter format="ditamap" href="dita_ot_installation/dita_ot_installation.ditamap">
        <topicmeta>
            <navtitle>DITA Open Toolkitのインストール</navtitle>
        </topicmeta>
    </chapter>
    <chapter collection-type="sequence" format="ditamap" href="jp_pdf_setup/jp_pdf_setup.ditamap">
        <topicmeta>
            <navtitle>PDF出力（FOプラグイン）の日本語化</navtitle>
        </topicmeta>
    </chapter>
    <chapter format="ditamap" href="dita_ot_execution/dita_ot_execution.ditamap" type="concept">
        <topicmeta>
            <navtitle>DITA Open Toolkitの実行方法</navtitle>
        </topicmeta>
    </chapter>
    <chapter collection-type="unordered" format="ditamap" href="pdf_customize/pdf_customize.ditamap">
        <topicmeta>
            <navtitle>PDF出力のカスタマイズ</navtitle>
        </topicmeta>
    </chapter>
    <chapter collection-type="unordered" format="ditamap" href="html_customize/html_customize.ditamap">
        <topicmeta>
            <navtitle>XHTML/HTML Help出力のカスタマイズ</navtitle>
        </topicmeta>
    </chapter>
    <backmatter>
        <booklists>
            <indexlist/>
        </booklists>
    </backmatter>
</bookmap>

この仕様変更はXMLの基本に忠実であることを目指したものと思われます。「生成物に現れるコンテンツを書くには、属性ではなく要素を使いましょう」というのがXMLの文書構造を設計するときの鉄則です。navtitleは、トピックタイトルをマップでオーバーライドするときに使います。このとき、navtitleで指定した文字列はトピックのタイトルとして生成物に現れます。

コメントを書く

2012-05-04

DITA-OT 1.6M3のカスタマイズ

DITA | 22:24 |

oXygenにバンドルされているDITA-OTが素晴らしく、かつ、迅速に最新バージョンに対応してくれるので、しばらくDITA-OTに触っていなかった。DITA-OTに触るのは2年ぶりくらいかな。DIAT-OT 1.5.3以降触っていなかったから。

久々に触ったら、ずいぶん変わっていたので驚き(*_*)　このまま触らないでいたら、ブラックボックスになっていたところだった。

●カスタマイズ対象のDITA-OT

5/4時点の最新テストビルド　1.6M3

●1.5xとの違い

(1) buildファイル

1.5xまでは、%DITA-OT%フォルダの下に、build_dita2htmlhelp.xml とか build_dita2xhtml.xml など、DITA-OTの各出力物を生成するためのビルドファイルがたくさんころがっていた。これらがスッキリなくなって、%DITA-OT%pluginsフォルダの下に整理されている。出力物共通のビルドファイルは、%DITA-OT%plugins\org.dita.baseの中に、他のビルドファイルは出力物の種類ごとに格納されている。

(2) buildファイルの中のtarget

buildファイルの中のtargetの構成も以前と随分変わった。例えば、様々な出力物を生成するときに呼ばれていた dita-preprocess というtargetがなくなった。これらtargetに関する変更のおかげで、1.5xで動いていたプラグインがそのままでは動かない。

(3) buildファイルの中のpropertyの定義の変更

buildファイルの中で定義されているpropertyの定義がいろいろと変わっているらしい。例えば、dita.temp.dirプロパティの定義が変わっているので、下記のようにパラメータの指定を変更しなければいけなかった。

[修正前]

[修正後]

コメントを書く

2012-04-30

DELL Vostro1200のHDDをCrucial m4 CT128M4SSD2に換装＋Windows7クリーンインストール

PC関連 | 21:39 |

私の愛用のノートPC DELL Vostro1200。2009年3月に購入して、これまでWindows XPで使い続けてきた。Intel 330 Seriesの発売開始の影響もあり、SSDの値段が手頃になってきたので、HDD→SSD、WindowsXP→Windows7への移行に踏み切った。DELLが提供しているVostro1200のドライバはVista 32bitまで。Windows7がちゃんと動くか不安があったものの、結果、無線LANをオフにできないという問題を除いて普通に使えるようになった。

PCの起動時間、シャットダウン時間は劇的に早くなって、大満足！！

●私の使っているノートPCのスペック(換装前)

モデル：DELL Vostro1200 Core2Duo T7250

メモリ：2GB 800MHz DDR2-SDRAM

HDD：160GB SATA 5400回転(WD1600BEVT)

OS：Windows XP Professional SP3(32bit)

PC起動時間(HDDアクセスランプが消えるまで)：約2分45秒

Cristal Disk MarkによるHDDベンチマークの結果

●今回換装したSDDと、インストールしたOS

SSD：Crucial m4 CT128M4SSD2

OS：Windows 7 Home Premium(32bit)

PC起動時間(SSDアクセスランプが消えるまで)：約40秒

シャットダウン時間：約7秒

Cristal Disk MarkによるSDDベンチマーク結果

●HDD→SSDへの交換作業

交換作業はいたって簡単。15分ほどで何の問題もなく完了した。

DELLのサポートページにあるサービスマニュアルの、「ハードドライブ」のセクションを見ると、HDDの取り外し方が丁寧に説明されている。これに従ってHDDを取り外し、代わりにSDDを付けて元に戻すだけ。

●Windows7のインストール

Windows7のインストールで気になっている点が１点だけある。

デバイスマネージャーを見ると、「Microsft ACPI-Compliant System」が不明なデバイスになっている。このドライバが関係しているのかどうか定かではないが、ファンクションキーを使って無線LANをオフにすることができない。

[2012.5.12追記]

ファンクションキーを使って無線LANをオフにすることはできないけれど、Windows7の標準機能、Windowsモビリティーセンターから無線LANをオフにすることはできる。

●Crucial m4 CT128M4SSD2のファームウェア

購入したCrucial m4のファームウェアはVer0309。Crucialウェブサイトのサポートページを確認したところ、2012/4/11にVer000Fがリリースされていた。ということで、HDD→SDD換装、Windows7インストールが済んだ後に、Firmware Update Utilityをダウンロードして、ファームウェアを更新した。

コメントを書く

2011-10-30

Cygwin上でREVIEWを動かす

EPUB, REVIEW | 17:10 |

市川せうぞーさんの記事「はじめてのReVIEW～InDesignへの取り込み」に触発されて、Windows上でREVIEWを動かしてみました。CygwinもTexも初めてだったので、大分苦労しました。EPUB出力は正常に行えるようになりましたが、PDF出力はまだ原因不明のエラーが発生します。が、一応動作するまでの手順をメモっておきます。

1) Cygwinにインストールする必要があるソフトウェア

・Ruby

・vi

・bsdtar

・git

・wget

・rebase

・TexLive2011（TexLive2011のインストール手順については下記ページ参照）

Using LaTeX in Japanese on Cygwin.

2) REVIEWのインストール手順

下記のページ参照

ReVIEW の使い方

ただし、TexLive2011へのフォントのインストールは別途行うので、「otf.styのインストール」以降の手順は行う必要なし。

3) REVIEWの要修正箇所

Cygwin固有の問題で、REVIEWを実行するためのRubyコマンドスクリプトに修正を加える必要がある。

review-epubmaker

499行目から

  # Zip epubファイルの作成。mimetypeは圧縮しないようにする
  fork {
    basedir = Dir.pwd
    Dir.chdir("#{tmp}/#{bookname}") {|d|
      exec("zip -0X ../#{bookname}.epub mimetype")
    }
  }
  Process.waitall
  fork {
    basedir = Dir.pwd
    Dir.chdir("#{tmp}/#{bookname}") {|d|
      exec("zip -Xr9D ../#{bookname}.epub META-INF OEBPS")
    }
  }

review-pdfmaker

436行目

unless File.directory?(dirname)

4) rebaseの実行

REVIEWを実行すると、多分、以下のようなエラーが出る。

$ review-epubmaker config.yml
      1 [main] ruby 4896 C:\cygwin\bin\ruby.exe: *** fatal error - unable to rem
ap \\?\C:\cygwin\lib\ruby\1.8\i386-cygwin\etc.so to same address as parent: 0x1A
0000 != 0x200000
Stack trace:
Frame     Function  Args
02407288  6102796B  (02407288, 00000000, 00000000, 00000000)
02407578  6102796B  (6117EC60, 00008000, 00000000, 61180977)
024085A8  61004F1B  (611A7FAC, 61243684, 001A0000, 00200000)
End of stack trace
      1 [main] ruby 4832 fork: child 4896 - died waiting for dll loading, errno
11
/home/hirai/review/bin/review-epubmaker:113:in `fork': Resource temporarily unav
ailable - fork(2) (Errno::EAGAIN)
        from /home/hirai/review/bin/review-epubmaker:113:in `main'
        from /home/hirai/review/bin/review-epubmaker:109:in `each_line'
        from /home/hirai/review/bin/review-epubmaker:109:in `main'
        from /home/hirai/review/bin/review-epubmaker:108:in `open'
        from /home/hirai/review/bin/review-epubmaker:108:in `main'
        from /home/hirai/review/bin/review-epubmaker:638

この問題を解決するために、Cygwinのrebaseallというコマンドを実行する。

4-1) Cygwinのコマンドプロンプトを閉じる。

4-2) Windowsのコマンドプロンプトを開く。

4-3) 以下のコマンドを実行する（Cygwinのインストール先がC:\cygwinの場合）

> cd c:\cygwin\bin
> ash
$ ./rebaseall

5) Cygwin.batの書き換え

以下のワーニングメッセージが出ないようにするために、Cygwin.batを書き換える。

cygwin warning:
  MS-DOS style path detected: C:/Users/hirai/AppData/Local
  Preferred POSIX equivalent is: /cygdrive/c/Users/hirai/AppData/Local
  CYGWIN environment variable option "nodosfilewarning" turns off this warning.
  Consult the user's guide for more details about POSIX paths:
    http://cygwin.com/cygwin-ug-net/using.html#using-pathnames

Cygwin.batにrem以降の２行を追加する。

@echo off

rem --- Cygwin が DOS 形式のパスについての警告を出力しないようにする
set CYGWIN=nodosfilewarning

C:
chdir C:\cygwin\bin

bash --login -i

ここまでの手順でEPUBの生成が可能になる。

PDFを生成する場合は、以降のセットアップを続ける。

6) PDF生成のためのフォント関連のセットアップ

TexLive2011への日本語フォントのセットアップ手順については、下記ページ参照。

日本語フォントのセットアップ

私の場合は、Adobe CS 4にバンドルされている小塚明朝、小塚ゴシックを使用。

上記ページの解説に従ってフォントをコピーし、フォントマップ(kozukaEmbed.map)を配置。

ls-Rデータベースを更新するために、Cygwinのコンソールから、

$ mktexlsr

を実行。

PDFファイルを生成するときに、kozukaEmbed.mapを使うようにreview-pdfmakerファイルを次のように書き換える。

135行目

      exec("dvipdfmx -f kozukaEmbed.map -d 5 book.dvi")

以上のセットアップが完了したら、一応PDFの生成が可能になるが、以下のようなエラーが発生してテキストの一部が欠落してしまう。

! Undefined control sequence.

原因は不明だが、REVIEWのバグ？

コメントを書く

2011-10-02

DITA4Publisherで生成したEPUBにSigilで手を加えてみた

DITA, EPUB | 22:51 |

EPUBに期待するところもあって、DITA4PublisherによるEPUB出力を実用に近づける努力をしてみた。とはいっても、DITA4Publisherをカスタマイズするのではなく、DITA4Publisherが出力したEPUBをSigilを使って編集。DITA4Publisherのカスタマイズは出力すべきものが決まってからということで（いつになるか分かりませんが・・・）。

私的な都合で、EPUBを読む環境はiBook(iPadとiPod Touch)に限定。ちょうど作業を始めたタイミングで、iBookが1.3.1にバージョンアップされた。このバージョンアップの改善項目なのかどうか今一つ自信がないが、以前から問題に思っていたいくつかの点がクリアされた。

【問題だった点】

~~ソースコードがディスプレイの端で切れてしまう→ディスプレイの端で折り返されるようになった~~
ハイパーリンクでブック内へジャンプした後、元のページに戻れない→画面左下に、元のページに戻るリンクが表示されるようになった（下図参照）

[2011.10.3追記] 1.はiBook 1.3.1へのバージョンアップによる改善項目ではありませんでした。CSSの設定によって、ディスプレイ幅に収まりきらない整形済みテキストの、表示のされ方が変わります。

1.については、まだ課題が残っている。ディスプレイ端での折り返しと改行の見分けがつかないので、ソースコードの書き方の工夫が必要。この課題は紙にソースコードを印刷する場合と同じだが、EPUBだと紙と違ってディスプレイサイズによって折り返し位置が変わってしまうので厄介だ。

【編集環境】

DITA-OT 1.5.3(oXygen Ver13にバンドルのもの)
Sigil Ver0.3.4
oXygen Ver13

SigilはVer0.4.2が出ているが、動作が不安定でEPUBファイルを読み込めないことがあるので、安定しているVer0.3.4を使用した。oXygen Ver13はスグレモノで、EPUBファイルの編集も可能だ。content.opfの編集はSigil Ver0.3.4ではできないので、oXygenを使って編集した。それなら、Sigilを使わずにoXygenを使ってすべての編集をすればよいものだが、ことEPUBの編集についてはSigilの方が安心感がある。すべてを自分で編集する自信があるならoXygenでもよいのだが、Sigilは難しいことを自動でやってくれるので、無難にEPUBを作ることができる。

【気が付いた点等】

●ナビゲーションリンクの出力制御

DITAコンテンツをXHTMLやHTML Helpに出力したときは、各トピックの末尾にナビゲーションリンクが表示される。EPUBにナビゲーションリンクはそぐわないので、出力を制御する方法がないか調べたら、epub.exclude.auto.rellinksというantパラメーターをtrueにすることで抑制できることがわかった。

●CSS

EPUBリーダーがiBookの場合は、XHTMLやHTML Help用に作ったCSSがほぼそのまま使える。

[2011.10.3追記]

●TOC

DITAの良いところは、マップが情報全体の構造を表している点にある。しかし、何も工夫をしていない状態のEPUBでは、トピックを読んでいるときにそのトピックがマップのどの位置にあるものなのかを容易に把握することができない。

【サンプルEPUBファイル】

DITA Open Toolkit活用ガイド　dita_ot_tips.epub
DITA1.1 ライティング・ガイド　writing_guide.epub

コメントを書く

mitsu48 2011/10/03 12:59 こんにちはSigilは初めて知りました．
このツールのよいところはePub出力した後のちょっとした処理をWYSIWYGで修正できるところということなのでしょうか．

ditahack 2011/10/03 22:31 Sigilはフリーで使える有名なEPUB編集ツールです。http://tutorial.epubcafe.jp/ などにも詳しい使い方が書かれています。
Sigilを使ってDITA4Publisherが生成したEPUBファイルを編集すると、「ちょっとした処理をWYSIWYGで修正する」以上の恩恵が得られます。例えば、BookIDが自動的に割り振られたり、OCFにパッキングされるファイル群のフォルダ構成が標準化されたりとか。