oXygen v17.1のDITA1.3サポート - Key scopes
DITA1.3の規格は、まだ、OASISで承認されていませんが、仕様はほぼ固まっています。oXygen v17.1でDITA1.3(experimental)がサポートされたことを知り、さっそく試してみました。
Syncro SoftのDITA1.3 Support紹介ビデオは こちら です。
今回試したのは、昨年のDITA Festaのときに発表した、「スコープ付きキー」(Key scopes)の機能です。
Key scopesを使うと、1冊のマニュアルの中で、トピックを再利用し、かつ、そのトピックの内容をコンテキストに応じて変えることができます。例えば、下図に示したように、「フィルターの交換手順」というトピックがあったとします。1冊のマニュアルの中に、MN-01, MN-02, MN-03という3つの製品モデルの説明を書きます。トピックの内容は、ほぼ同じなのですが、モデル名やイラストを製品モデルごとに変えなければいけません。サービスマニュアルなどでは、よくあるケースだと思います。
このようなケースでは、可変にするモデル名とイラストをキー参照にして、次のようにトピックを書きます。モデル名はstr_model、イラストはimg_engineというキー名になっています。
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA 1.3 General Task//EN" "generalTask.dtd"> <task id="task_rb1_xvk_54" xml:lang="ja-JP"> <title>オイルフィルタの交換手順(<ph keyref="str_model"/>)</title> <prolog> <metadata> <keywords> <indexterm><ph keyref="str_model"/> <indexterm>オイルフィルタ</indexterm></indexterm> </keywords> </metadata> </prolog> <taskbody> <prereq> <p><u>用意するもの</u></p> <ul> <li>オイルフィルタレンチ</li> <li>オイルパン</li> <li>新しいオイルフィルタ</li> <li>新しいエンジンオイル</li> </ul> </prereq> <context> <p><u>予備知識</u></p> <p>エンジンオイルを交換するとき、2回に1回はエンジンオイルフィルタもいっしょに交換してください。</p> <image placement="break" id="image_ybk_3yk_54" keyref="img_engine"/> </context> <steps> <stepsection><u>手順</u></stepsection> <step id="step_wwj_bzk_54"> <cmd>エンジン<ph keyref="str_model"/>の下にオイルパンを置き、エンジンオイルのドレインボルトを取外します。</cmd> </step> <step id="step_lxj_bzk_54"> <cmd>エンジンオイルがほとんど落ちなくなるまで待ちます。</cmd> </step> <step id="step_p2f_tzk_54"> <cmd>オイルフィルタを取外します。</cmd> </step> <step id="step_u51_5zk_54"> <cmd>新しいオイルフィルタのO-リングに少量のエンジンオイルを塗布してから、オイルフィルタを取付けます。</cmd> </step> <step id="step_vsk_11l_54"> <cmd>ドレインワッシャを交換し、ドレインボルトを取り付けます。</cmd> </step> <step id="step_vlc_f1l_54"> <cmd>新しいエンジンオイルを注入します。</cmd> </step> <step id="step_kyg_g1l_54"> <cmd>オイルレベルゲージでエンジンオイル量を確認します。</cmd> </step> <step id="step_mvz_k1l_54"> <cmd>オイルフィラキャップを締めます。</cmd> </step> </steps> </taskbody> </task>
マップからトピックを参照するとき、キー定義の有効範囲をkeyscope属性で指定します。
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map xml:lang="ja-JP"> <title>Keyref sample-01</title> <topicref href="t_change_filter.dita" copy-to="t_change_filter_MN-01.dita" keyscope="MN-01"> <keydef keys="str_model"> <topicmeta> <keywords> <keyword>MN-01</keyword> </keywords> </topicmeta> </keydef> <keydef keys="img_engine" href="img/MN_01.png" format="png"/> </topicref> <topicref href="t_change_filter.dita" copy-to="t_change_filter_MN-02.dita" keyscope="MN-02"> <keydef keys="str_model"> <topicmeta> <keywords> <keyword>MN-02</keyword> </keywords> </topicmeta> </keydef> <keydef keys="img_engine" href="img/MN_02.png" format="png"/> </topicref> <topicref href="t_change_filter.dita" copy-to="t_change_filter_MN-03.dita" keyscope="MN-03"> <keydef keys="str_model"> <topicmeta> <keywords> <keyword>MN-03</keyword> </keywords> </topicmeta> </keydef> <keydef keys="img_engine" href="img/MN_03.png" format="png"/> </topicref> </map>
このマップでは、1つのトピックを3箇所から参照しています。それぞれの箇所で、モデル名とイラストの実態を指定しています。このとき、topicref要素のkeyscope属性を使って、キーの有効範囲を指定するのがポイントです。こうすれば、同じ名前のキーに対して、異なる実態を指定できるようになります。
PDFをパブリッシュしてみると、ちゃんとモデル名とイラストが変わっていることが確認できます。
このKey scopesを使ったトピックをoXygen v17.1で編集すると、コンテキストに応じて、ちゃんとキー参照のプレビューを表示してくれるのです。
素晴らしい!! です。
oXygen V17 属性値のドロップダウンリスト表示
oXygenには、highlightプラグインがバンドルされていて、ソースコードを見やすくパブリッシュできます。ソースコードをハイライトさせるには、codeblock要素のoutpuclass属性にソースコードの言語を指定します。このとき、outputclass属性に指定可能な値がドロップダウンリストで表示されるので、とても便利です。
他の属性についても同様にドロップダウンリストを表示させることができます。そのときは、Subject Schemeを使います。手順はSyncRO SoftのVideo Tutorialで分かりやすく紹介されています。
Subject Schemeもいいのですが、トピックを編集するときにマップを開いておかなければいけないのが、イマイチ。codeblock@outputclassは、マップを開いておかなくてもドロップダウンリストが表示されます。どうなっているのかSyncRO Softのサポートに聞いてみたら、V16.1まではJavaでハードコーディングされているとのこと。
「しかたないなぁ」と思っていたら、
なんと、V17では属性値を制限する機能が「設定ファイルを書き換えるだけ」で実現できるように改善されているとの朗報！さっそく、V17β版をダウンロードして試してみました。
設定ファイルの場所は、
OXYGEN_17_INSTALL_DIR\frameworks\dita\resources\cc_value_config.xml
中身はこんな感じで書きます。
<!-- Contributes values to the given attribute from the given element --> <match elementName="table" attributeName="outputclass"> <items action="addIfEmpty"> <item value="normal" annotation="フォントサイズ：標準、パディング：標準"/> <item value="narrow" annotation="フォントサイズ：標準、パディング：狭い"/> <item value="small-font" annotation="フォントサイズ：小さい、パディング：標準"/> <item value="condensed" annotation="フォントサイズ：小さい、パディング：狭い"/> </items> </match>
結果はこのとおり。
oXygenは、かゆいとろこに手がとどくんだよね。
「なんでこんなに気が利くんだろう」と、いつも不思議に思ってたんですが、ブログの記事を読んで納得しました。すべてのソフトウェア会社が、こうあって欲しいものだと。。。
DITA for Printはすばらしい！！
Elio Kimberさんのtwitterをフォローしているのですが、「XMLPressの電子ブックが半額セール実施中」のつぶやきに誘われて、「DITA for Print」を衝動買い。
あまり期待していなかったのですが、ちょっと中身を読んでみたら「これはスバらしい本だ！！」ということが分かりました。DITA-OTのPDF2プラグインをカスタマイズする手順が、実に詳細に、分かりやすく書かれています。
といった、DITA-OTからのPDF出力のカスタマイズに必要な一通りのことが、実に丁寧に解説されています。
解説の後に、必ず実践的な練習問題が付いて、その解答のコードがそのまま実務でも利用できます。
DITA-OT標準のPDF2以外のプラグインを使われている方にも、非常に勉強になる１冊だと思います。
DITA Open ToolkitドキュメントのソースをGitHubからゲット
大事なことを書き忘れました。
DITA Open Toolkitのドキュメントのソース（DITAマップとDITAトピック）ファイルは、プログラムのソースコードといっしょにGitHubにチェックインされています。ということは、GitHubからDITAソースファイル一式を入手できるということです。これは、DITAの書き方を勉強する材料としても最適！
GitHubからソースコードをダウンロードするには、zipで固められたファイルをダウンロードする方法と、github for Windowsを使ってgitリポジトリを自分のPCにコピーする方法があります。後者の方法が断然おススメ。私もGitHubを使うのは初めてでしたが、インターネットの情報を参考にやってみたら、超かんたん！最近、オープンソースの発展が目覚めしい理由の一つはコレかぁ、と気づいてしまいました。
DITA Open Toolkitのドキュメント
DITA Open Toolkitのドキュメント(DITA Open Toolkit 1.8)が素晴らしく改善されているので、うれしくて記事を書いています。
DITA Open Toolkitの開発リポジトリは、SourceForgeからGitHubへ移っています。DITA Open ToolkitのドキュメントもGitHubから公開されており、以下の3つのドキュメントがあります。
- Getting Started
- User Guide
- Developer Reference
何が改善されているかというと、まず、読みやすさです。CSSが適切に調整されていて、ディスプレイ上で読みやすくなっています。
次に、文章がきちんとリライトされ、ノンネイティブでも理解しやすいようにすっきり書かれています。内容も、最新のDITA Open Toolkitの仕様に合わせてきちんと更新されています。
どうやって作ってるんだろう・・・？
と思ってソースを見てみたら、なんと先頭行が<!DOCTYPE html>
そう、HTML5になっているではありませんか。
具体的な作り方を知りたくて、Yahoo DITA Users Groupにメッセージを投げてみたところ、DITA Open ToolkitのメインのcommitterであるJarnoさんが答えてくれました。
DITAソースをDITA Open ToolkitでHTML5に変換変換して、各ページと目次を生成した後、Jekyllを使ってWebサイトコンテンツにまとめているとのこと。
Jekyllって初めて聞いたのですが、ちょっと調べてみたところ、ブログ風のサイトを構築するための、Rubyで書かれたファイルジェネレーターだそうです。このしくみって、ソフトウェア製品のオンラインマニュアル生成に最適なんじゃないかと思いました。DITA Open Toolkitのドキュメントのソース（DITAマップとDITAトピック）は、DITA Open ToolkitのプログラムのソースコードといっしょにGitHubで管理されています。新しいレビジョンをビルドすると、ドキュメントの内容も自動的に更新され、所定のWebサイトにアップされます。
Coolですねぇ。
Webinarで学んだOxygenの新しい機能
最近、Oxygenの開発元、Syncro Soft SRLが、ちょくちょくWebinarを開催しています。興味があったので申し込みをしておいたものの、時差の関係で日本では深夜になってしまうので、結局見逃してしまいました。アーカイブが公開されたとのお知らせメールが入ったので、早速見てみたところ、またまたOxygenが進化していました。
今回紹介されていたのは、マップ編集のユーザーインタフェースの機能拡張で、
1) Edit Attributes in-place
2) Show Topic Titles
の2つ。
Edit Attributes in-place
これは、ビジュアルエディターのビューの中に、属性を編集するための、チェックボックス、テキストボックス、ドロップダウンリストなどのGUIを表示させるモードです。属性をたくさん指定する必要があるときに便利なモードです。
デフォルトの設定だと、マップ編集時のビジュアルエディターはこんな感じで表示されます。
Edit Attributes in-placeを選択すると、こんな感じで表示されます。
Show Topic Titles
Oxygenでは、以前から「エディタ内で解決されたトピックと共にマップを開く」を使えば、マップといっしょに参照先のトピックを見ることができました。Show Topic Titlesを選択すると、トピックを開かずに、参照先のトピックのタイトルだけが下図のように表示されます。
5月29日に、また、Webinarが予定されているので、とりあえず申し込んでおきました。きっと、終わってからアーカイブを見ることになると思いますが(^_^;)
EPUB3にSVGを挿入するときの問題
XMLmind DITA Converter v2.4 を使うと、DITAからEPUB3が簡単に作れることが分かったので、いろいろ試していました。
EPUB3では図にSVGが使えます。SVGが使えると、EPUB3でマニュアルを作るときのいろいろな問題が解決できるので、とても期待しています。
EPUB3へのSVG挿入でハマったというか、分かったことが２つ。
手元にはiPad miniしかないので、iBooks(v3.1)以外では未検証です。
ビットマップとベクターを組み合わせたSVGを挿入するときは
これは解せない挙動なので、私がまだよく分かっていないことがあるのかもしれません。ご存知の方がいらっしゃいましたら、是非、ご教示をお願いします。
ベクターだけで構成されたSVGを挿入するときは、XHTMLのコードは下記のように外部参照で書いておけば、ちゃんと図が表示されました。
<img src="img/sample.svg" id="xxx" class="image max-width" alt="Sample SVG Graphics" />
ところが、ビットマップとベクターを組み合わせたSVGを同様に外部参照で書いてEPUB3を生成すると、ビットマップが表示されずにベクターの部分だけが表示されるのです。
いろいろ試して見つけたワークアラウンドが、
<foreign> <svg> : </svg> </foreign>
これで、ビットマップとベクターの両方が表示されます。
