Mr.DITA Japan Blog 2015/2

DIT-FMxにおけるcoderef要素

[DITA FrameMaker] 投稿日時:2015/02/26(木) 23:42

DITA 1.2から実装されたcoderef要素は、DITAトピックにプログラムのコードなどを外部に置いたまま参照する場合に便利な要素です。ユースケースとしては、例えばAPIリファレンスにおいてSVNなどのソース管理システムで管理されているコードを実際の例として参照したい場合などです。codeblockの内容をcoderefとして参照していれば、コードは常に最新版で正確であるので安心です。長いコードやPDFにフォーマットする場合などは親のcodeblockexpanse属性値の値をルール化したりする工夫が必要ですが、便利な要素です。

ただし、coderef要素をビジュアルな編集モードで読み取り不可のコンテンツブロックとしてコンテンツ参照のように表示されことができるのは、今のところ、DITA-FMxだけのようです。VARでもあるoXygenをはじめ、Arbortext、XMetaLのどれもが機能をもっていませんでした。oXygenは機能要求しておきましたので、近いうちにDITA-FMxと同等の機能が実装されるでしょう。ドラッグ&ドロップでcoderefを挿入できればユーザビリティーが増しますので、これも一緒にリクエストしておきました。


 

DITA文書における索引付け(DITAスタイルガイド)

[DITAスタイルガイド] 投稿日時:2015/02/23(月) 04:10

索引付け

DITAにおける索引付け機能は、以下の3つの索引関連要素から構成されています。indexterm、index-see、index-see-also要素です。これらの要素は、技術仕様的には、トピック本体のどの場所にでも入力できます。 トピックprolog要素内や、DITAマップ内のトピック参照内topicmeta要素においても同様に入力できます。しかしながら、翻訳や処理においての複雑さを避けるためには、これらの要素は、意図的に、トピックやマップの特定の場所に入力するべきです。

indexterm要素の入力場所

文書内のトピックに渡って執筆者が入力した索引キーワード語から、パブリッシングの工程で、アルファベット順(五十音順)にソートされた索引が自動生成されます。索引キーワード語は、indexterm要素をとおして定義されます。

DITAはindexterm要素を以下の場所に入力できます。

  • DITAマップのtopicref要素内
  • トピックのprolog要素内
  • トピックのshortdesc(abstract)要素内
  • トピックのbody(ほかの継承要素も含む)要素内

しかしながら、索引エントリをテキスト中のあちこちに入力するのは、保守や管理における問題を作り出し、翻訳や処理において困難な状況を引き起こすことに成りかねません。

よってできる限り、 indexterm要素はトピック内のprologセクションやトピックコンテンツ本体の外部に入力すべきです。prolog要素内では、索引エントリーはkeywords要素に囲まれていなければなりません。

パブリケーション固有(よってトピックに入力するのが必ずしも適切でない)の場合は、indexterm要素はDITAマップ内のtopicref要素内の topicmetaセクションに入力すべきです。わかりやすい事例としては、語句がひとつの組織以外では使われず、他の組織とは異なる出力をDITAマップにおいて定義する場合です。

索引語は、トピックが比較的長文の場合のみ、トピックの本文中に入力されるべきです。このような場合、索引エントリの出現場所は、語句が述べられている位置では無く、コンテンツ内のセクションの始まる位置であるべきです。

索引エントリをトピック本文中に入力しなければならない場合は、以下の入力ガイドラインに従ってください。

  • ブロック(段落)要素:含まれている要素の開始タグのすぐ後
  • センテンスレベル:センテンスのすぐ前
  • 単語やフレーズレベル:テキストのすぐ前

: indexterm要素のコンテンツは、indexterm要素がインラインでコンテンツの本文中にあっても、出力表示されることはありません。それゆえ、マークアップ:

<p>The EJ25<indexterm>turborcharger</indexterm> forced induction...は、
The EJ25 forced induction...として出力表示されます。

特別な状況下において、indextermをindextermが許されていない特別な位置に使いたいという思いに駆られる場合があるかもしれません。フレーズ(ph)要素を挿入してから、ph要素内にindexterm要素を挿入することで、技術的には問題を回避することができるかもしれませんが、この方法はしないでください。要素として妥当な場所にのみ索引語句を挿入してください。

このブログポストテーマでは、弊社で準備中のoXygenの状況依存スタイルガイド参照機能やトニー・セルフ著の「The DITA StyleGuide」出版前のドラフト日本語翻訳原稿をWork-in-Progressとして一部のコンテンツを抽出してアップしています。oXygen状況依存ヘルプは、弊社にてoXygenライセンスをご購入のユーザー様にオプションサービスとして提供を予定しています。

 

FrameMakerにおけるDITA索引エントリーの入力

[DITA FrameMaker] 投稿日時:2015/02/22(日) 00:16

DTPアプとしてのFrameMakerの操作に慣れたユーザーにとっては真新しいことではありませんが、FrameMakerにおける索引エントリー(indexterm)の入力は、マーカー内のマーカーテキストとして入力します。日本語のソートに必須の「よみがな」もふることができます。レベル化することも非構造化の文書作成環境ではでき、通常の業務においては支障をきたすことはありません。しかしながら、構造化FrameMakerのDITA環境では、階層を加えるレベル付けされた索引エントリーを作成することはできません。これでは情報をトピックのキーワード索引エントリー経由で探し易くするというDITA情報アーキテクチャの考えを満たすことはできません。また、この機能制限によって他のDITAオーサリングツールとの互換性が保たれなくなってしまいます。では、FrameMakerユーザーはどう対処したらよいのでしょうか?DITAオーサリングのために新しいDITAオーサリングツールを購入し、操作方法を新たに学ばなければいけないのでしょうか?非構造化とXMLによる構造化文書の両方の作成ができるコストパフォーマンスの高い、使いやすく便利なツールから離れなければならないのでしょうか?答えはNOです。

DITA FMx FrameMakerプラグイン

FrameMakerではDITAの文書作成はできないのか、と落胆する必要はありません。FrameMakerに他のDITAオーサリングツールと同等の機能を追加してくれるアドオンツールが存在します。Leximation社のDITA-FMxです。

DITA FMxがインストールされた環境では、DITAのindexterm要素(エレメント)は、FrameMaker編集環境では、fm-indextermというDITA-FMx拡張のための要素(エレメント)に置き換えられ、マーカーとして扱われます。DITA保存時には、自動的にindexterm要素に戻され双方向にそれぞれ互換性が維持されます。DITAマップからのFMのブック作成時には、索引エントリーとして取り込まれレベル化された索引エントリーを持つ索引ページが自動生成されます。下の2つの緑で囲まれた部分がそれぞれ2階層にレベル化されたindextermのオーサリング例です。

標準的なDITAエディターoXygenにおけるオーサーモード編集画面

FrameMaker+DITA-FMxにおけるWYSIWYGビュー編集画面

DITA-FMxプラグインをインストールすることによってレベル化された索引エントリーをはじめとするDITAオーサリングにおける拡張機能やプロフェッショナルな美しいFrameMakerのブックパブリッシングをDITAコンテンツ開発環境にもたらします。

以降のDITA FrameMakerシリーズのブログポストでは、DITA文書化プロセスにおけるFrameMakerおよびFrameMaker XML AuthorとDITA-FMxとの併用による、これまであまり語られることの無かったDITA文書化プロセスの実践をひも解いて行きたいと思います。