Hatena::ブログ(Diary)

文書遊戯 このページをアンテナに追加 RSSフィード Twitter

2015-10-24

oXygen v17.1のDITA1.3サポート - Key scopes

| 17:18 | 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つの製品モデルの説明を書きます。トピックの内容は、ほぼ同じなのですが、モデル名やイラストを製品モデルごとに変えなければいけません。サービスマニュアルなどでは、よくあるケースだと思います。

f:id:ditahack:20151024162712p:image

このようなケースでは、可変にするモデル名とイラストをキー参照にして、次のようにトピックを書きます。モデル名は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をパブリッシュしてみると、ちゃんとモデル名とイラストが変わっていることが確認できます。

f:id:ditahack:20151024162713p:image

このKey scopesを使ったトピックをoXygen v17.1で編集すると、コンテキストに応じて、ちゃんとキー参照のプレビューを表示してくれるのです。

D

素晴らしい!! です。

2015-04-25

oXygen V17 属性値のドロップダウンリスト表示

| 16:40 | oXygen V17 属性値のドロップダウンリスト表示を含むブックマーク

oXygenには、highlightプラグインがバンドルされていて、ソースコードを見やすくパブリッシュできます。ソースコードをハイライトさせるには、codeblock要素のoutpuclass属性にソースコードの言語を指定します。このとき、outputclass属性に指定可能な値がドロップダウンリストで表示されるので、とても便利です。

f:id:ditahack:20150425160416p:image

他の属性についても同様にドロップダウンリストを表示させることができます。そのときは、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>

結果はこのとおり。

f:id:ditahack:20150425160417p:image

oXygenは、かゆいとろこに手がとどくんだよね。

「なんでこんなに気が利くんだろう」と、いつも不思議に思ってたんですが、ブログの記事を読んで納得しました。すべてのソフトウェア会社が、こうあって欲しいものだと。。。

2013-12-14

DITA for Printはすばらしい!!

| 20:40 | DITA for Printはすばらしい!!を含むブックマーク

Elio Kimberさんのtwitterをフォローしているのですが、「XMLPressの電子ブックが半額セール実施中」のつぶやきに誘われて、「DITA for Print」を衝動買い。

あまり期待していなかったのですが、ちょっと中身を読んでみたら「これはスバらしい本だ!!」ということが分かりました。DITA-OTのPDF2プラグインをカスタマイズする手順が、実に詳細に、分かりやすく書かれています。

  • プラグインの作り方
  • アトリビュートセットの一覧
  • DITA-OTが生成するXSL-FOのスキーム
  • 表紙、目次、本文、索引、裏表紙、リンクのカスタマイズ
  • リソースのローカライズ
  • 特殊化対応

といった、DITA-OTからのPDF出力のカスタマイズに必要な一通りのことが、実に丁寧に解説されています。

解説の後に、必ず実践的な練習問題が付いて、その解答のコードがそのまま実務でも利用できます。

DITA-OT標準のPDF2以外のプラグインを使われている方にも、非常に勉強になる1冊だと思います。

2013-12-07

DITA Open ToolkitドキュメントのソースをGitHubからゲット

| 18:11 | DITA Open ToolkitドキュメントのソースをGitHubからゲットを含むブックマーク

大事なことを書き忘れました。

DITA Open Toolkitのドキュメントのソース(DITAマップとDITAトピック)ファイルは、プログラムのソースコードといっしょにGitHubにチェックインされています。ということは、GitHubからDITAソースファイル一式を入手できるということです。これは、DITAの書き方を勉強する材料としても最適!

GitHubからソースコードをダウンロードするには、zipで固められたファイルをダウンロードする方法と、github for Windowsを使ってgitリポジトリを自分のPCにコピーする方法があります。後者の方法が断然おススメ。私もGitHubを使うのは初めてでしたが、インターネットの情報を参考にやってみたら、超かんたん!最近、オープンソースの発展が目覚めしい理由の一つはコレかぁ、と気づいてしまいました。

DITA Open Toolkitのドキュメント

| 17:52 | 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ですねぇ。

mitsu48mitsu48 2013/12/09 10:58 最近oXygenの中で作業していたのでDITA-OTをご無沙汰にしていたら,Githubに移られていてびっくりしました。
まだフォローしきれていないのですが,社内との差分管理には助かります。
リンク先のHTMLも綺麗に整形されていますね。これがデフォルトだと支障なく外に出せそうです。

ditahackditahack 2013/12/09 22:34 私も、oXygenで事足りていたので、しばらくDITA-OTをFollowしてませんでした。
仕事でDITA-OTのプラグインを開発することになったので、久しぶりに調べたところです。
プラグイン開発についても、ドキュメントが随分分かりやすくリライトされていて、プラグイン開発の敷居が低くなりました。

2013-05-19

Webinarで学んだOxygenの新しい機能

| 23:38 | Webinarで学んだOxygenの新しい機能を含むブックマーク

最近、Oxygenの開発元、Syncro Soft SRLが、ちょくちょくWebinarを開催しています。興味があったので申し込みをしておいたものの、時差の関係で日本では深夜になってしまうので、結局見逃してしまいました。アーカイブが公開されたとのお知らせメールが入ったので、早速見てみたところ、またまたOxygenが進化していました。

今回紹介されていたのは、マップ編集のユーザーインタフェースの機能拡張で、

1) Edit Attributes in-place

2) Show Topic Titles

の2つ。

Edit Attributes in-place

これは、ビジュアルエディターのビューの中に、属性を編集するための、チェックボックス、テキストボックス、ドロップダウンリストなどのGUIを表示させるモードです。属性をたくさん指定する必要があるときに便利なモードです。

デフォルトの設定だと、マップ編集時のビジュアルエディターはこんな感じで表示されます。

f:id:ditahack:20130519232640p:image

Edit Attributes in-placeを選択すると、こんな感じで表示されます。

f:id:ditahack:20130519232748p:image

Show Topic Titles

Oxygenでは、以前から「エディタ内で解決されたトピックと共にマップを開く」を使えば、マップといっしょに参照先のトピックを見ることができました。Show Topic Titlesを選択すると、トピックを開かずに、参照先のトピックのタイトルだけが下図のように表示されます。

f:id:ditahack:20130519233222p:image

5月29日に、また、Webinarが予定されているので、とりあえず申し込んでおきました。きっと、終わってからアーカイブを見ることになると思いますが(^_^;)