キーおよびキー参照の使用

Arbortext Editor は、OASIS「DITA Architectural Specification」の「Key based (indirect) addressing」セクションで定義されたキーベースの参照をサポートしています。Arbortext Editor ユーザーインタフェースは、DITA マップでのキー定義と、マップおよびトピックへのキー参照の挿入の両方に役立つ多数の機能を提供します。さらに、Arbortext Editor は DITA キー定義マップと呼ばれるキー定義だけを含むことを意図して特化された DITA マップを提供します。このマップによって、ユーザーはキー定義に情報を追加することができます。

キー定義を格納するためには、キー定義だけを保持するために特化した DITA マップを持つことをお勧めします。このようにすると、mapref エレメントを使用して、必要に応じてその他すべての DITA マップにキー定義を持つマップを包含することができます。DITA キー定義マップを使用してキー定義を保存するよう、お勧めします。

Arbortext Editor の以下のユーザーインタフェースは、キー参照をサポートしています。

◦ 「キー参照の検索」 - 「キーおよびキー参照」ダイアログボックスを開き、カーソルが含まれるタグを含むキーのみを表示します。

• 「マークアップ」ツールバーには「キー参照の挿入」

ボタンがあります。このボタンにより、「キー参照の挿入」ダイアログボックスが開きます。

キー定義を修正するこのタブのバージョンは、「属性の修正」ダイアログボックス、文書マップ、および列ビューから使用することができます。

◦ 「Keyref」オプションは、コンテンツ参照用のものを除くすべての「リソースマネージャ」タブおよびダイアログボックスで使用可能で、作成または修正中の参照の keyref 属性に挿入するキー名を入力または選択することができます。

◦ 「Conkeyref」オプションは、コンテンツ参照用の「リソースマネージャ」タブおよびダイアログボックスで使用可能で、作成または修正中の参照の conkeyref 属性に挿入するキー名を入力することができます。

◦ 「リンク/Xref」、「コンテンツ参照」、および「トピック」タブおよびダイアログを使用すると、キー定義を含む DITA マップをブラウズし、挿入または修正された参照用に選択されたキー定義を使用することができます。

◦ 「マップの追加/除去」 - 「キー参照の挿入」ダイアログボックスのキー定義を指定するマップリストのマップを追加、または除去できます。

◦ 「参照を選択」 - 参照しているエレメントに複数の定義済み参照ターゲットが存在する場合に、どの文書を開くか選択することができます。

◦ 「キーおよびキー参照」 - 現在の文書と、現在の文書から参照されるすべての文書に含まれるキー定義およびキー参照を表示します。

デフォルトでは、キー参照ユーザーインタフェースは Arbortext Editor で使用できます。DITA 文書作成でキー参照を使用していない場合は、ユーザーインタフェースからキー参照機能を除去することができます。

キー参照ユーザーインタフェースを使用できるかどうかは、ditakeyrefui アドバンス環境設定によって制御されます。この環境設定の値を off に設定すると、キー参照ユーザーインタフェースが除去されます。

Arbortext Editor でキー参照に関連付けられたキー定義を検索するには、現在の文書のキーコンテキストがわかっている必要があります。キーコンテキストとは、関連するキー定義を含む DITA マップです。定義を含むマップが DITA キー定義マップである場合は、キー参照ユーザーインタフェースに表示されるキー定義に付加的情報を追加することができます。文書のキーコンテキストは ditakeycontext 設定オプションによって決定されます。

ditakeycontext オプションは単一のマップに設定され、現在の文書に対する現在のセッション中のプライマリキーコンテキストを定義します。文書に確立されたキーコンテキストが存在する場合、これは Arbortext Editor の参照の処理方法に影響を与えます。たとえば、イメージタグに href 属性と Keyref 属性の両方が定義されている場合、Arbortext Editor は Keyref 属性のキー定義からのイメージを表示します。Arbortext Editor では、一致するキー定義を含む確立されたキーコンテキストが存在する場合、キー参照またはコンテンツキー参照に優先権を付与します。

ユーザーが明示的に ditakeycontext を設定できますが、一部のケースでは Arbortext Editor によってこれが自動的に設定されます。たとえば、相互参照、トピック参照などをダブルクリックすることによって文書を開いた場合、元の文書のキーコンテキストが新しく開かれた文書に適用されます。同様に、Arbortext Editor の DITA 関連のダイアログボックスから文書を開くと、現在の文書のキーコンテキストが開かれた文書に適用されます。元の文書がキーコンテキストを持たない DITA マップである場合は、そのマップは開かれた文書のキーコンテキストになります。

文書に挿入できるキー定義を指定するもう 1 つのオプションは、ditakeybaselist 設定オプションです。「キー参照の挿入」ダイアログボックスおよびリソースマネージャの「Keyref」オプションに表示されるキー定義に使用されるマップのリストを作成するには、第 1 に ditakeybaselist オプションを使用します。ditakeycontext とは異なり、ditakeybaselist はアドバンス環境設定であるため複数のマップを含むことができ、複数の Arbortext Editor セッションを超えて存続することができます。ditakeybaselist に割当済みの値と、現在の ditakeycontext がリストに含まれていないマップが存在する場合、キーコンテキストマップは現在のセッションの ditakeybaselist マップリストの先頭に追加されます。

Arbortext Editor は、DITA キー定義マップと呼ばれる特殊な DITA マップを提供します。このマップは、キー定義で詳細な情報を指定することができる付加的なエレメントを含み、キー定義の保存のみに使用することを意図したものです。付加的なキー定義情報は、キー参照ユーザーインタフェースのさまざまな場所に表示されます。DITA キー定義マップは「新規」ダイアログボックスの「DITA Technical Content」カテゴリにあります。

キー定義マップは、キー定義に関する詳細情報を提供する topicmeta エレメントに付加的なエレメントを追加します。これらのエレメントを使用するには、keydef エレメントをマップに挿入し、topicmeta エレメントを keydef エレメントに、keyinfo エレメントを topicmeta エレメントに挿入します。さらに、keyinfo 内で使用する新しいメタデータエレメントのいずれかを挿入します。また、リソースマネージャの「キー定義」タブをキー定義マップで使用して、この付加的な情報をキー定義に追加することもできます。

以下の追加エレメントは、topicmeta で通常のキー参照として使用可能です。

Arbortext Editor のキー参照を通じてコンテンツを置換するには、エレメントに対して Conkeyref 属性を使用してコンテンツキー参照を設定する必要があります。通常のキー参照と同様に、コンテンツキー参照が文書のキーコンテキストに関連する定義を含み、エレメントに conref 属性と conkeyref 属性の両方が定義されている場合、Arbortext Editor は conkeyref と関連付けられたコンテンツを表示し、通常はキーコンテキスト参照を優先させます。

通常のキー参照を使用して、コンテンツキー参照のキーを設定することができます。ただし、DITA キー定義マップは、コンテンツ参照のキー定義に役立てることができるいくつかの付加的なエレメントを提供します。また、「キー参照の挿入」ダイアログボックスにコンテンツキー参照を含めるには、DITA キー定義マップで関連のキー定義を指定する必要があります。以下の追加エレメントは、コンテンツキー参照に使用できます。

このエレメントは、keydef エレメントを特殊化したものです。keyconrefs によって定義されたキー名を参照するトピックまたはマップ内の ID 付きのエレメントは、「キー参照の挿入」ダイアログボックスに conkeyref 参照のターゲットとして表示されます。このエレメントの scope 属性は、local に設定されます。format 属性は dita (デフォルト) または ditamap のいずれかに設定されます。

このエレメントは新しい keyinfo エレメントと、そのすべてのサブエレメントも含みます。keyconrefs 定義で keysubelementid エレメントに値を割り当てると、特定の ID を持つエレメントだけが、その定義を使用するコンテンツキー参照として使用可能になります。それ以外の場合は、ID を持つすべてのエレメントを使用できます。

このエレメントは keyinfo エレメントに含まれます。keyforconrefs エレメントの value 属性が true (デフォルト) に設定されている場合、これは該当のキー定義がコンテンツキー参照用であることを示し、「キー参照の挿入」ダイアログボックスではそのように取り扱われます。これにより、ユーザーは keydef およびその他のエレメントをマップで使用して、コンテンツキー参照のキー定義を指定することができます。

DITA キー定義マップを使用すると、ユーザーはコンテンツキー定義を設定して、単一のエレメントをコンテンツキー参照として使用できるようにすることも、ID のあるすべてのエレメントを使用できるようにすることもできます。「キー参照の挿入」ダイアログボックスで、単一のエレメントを conkeyref 参照に使用できるようにするには、DITA キー定義マップで以下のマークアップを使用して、これを定義する必要があります。

• keyreftags エレメントの value 属性は、文字列 conkeyref: をプレフィックスとして、特定の ID を持つエレメントの名前を含む必要があります。

たとえば、次のキー定義はトピック strings.dita 内の ID custom を持つ ph エレメントを「キー参照の挿入」ダイアログボックスに conkeyref ターゲットとして追加します。

<keydef keys=”strings” href=”strings.dita”>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>

「キー参照の挿入」ダイアログボックスの conkeyref 参照のマップまたはトピックで ID を持つすべてのエレメントを使用できるようにするには、DITA キー定義マップでもそのことを定義する必要があります。このマークアップは、以下のいずれかの方法で定義できます。

• topicmeta エレメントの keyinfo エレメント内の keyforconrefs エレメントとともに、すべての有効なエレメントを使用してキー定義を指定します。

通常のキー参照を使用して、文書にテキストを挿入することもできます。多くの DITA エレメントには keyref 属性があります。エレメントが空でキー参照が設定されている場合、キー定義にテキストを追加して、これらのエレメントに挿入することができます。テキストの挿入に使用するには、エレメントが空である必要があります。たとえば、文書内に次のエレメントが存在するとします。

キーは次のキー定義を参照します。

文書をパブリッシングすると、次のテキストが ph エレメントに挿入されます。

挿入するテキストにマークアップを含めることもできます。たとえば、キーが次のキー定義を参照した場合:

次のテキストが文書に挿入されます。

テキストを挿入するほかに、キー定義に href 属性を含めることで、リンクでないエレメントをリンクエレメントに変換したり、その逆の変換を行うこともできます。たとえば、次のキー定義について考えてみます。

<keydef keys="product-name" href="acme.dita">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>

これらのキー定義は、文書内の次のエレメントによって参照されています。

文書をパブリッシングすると、次のテキストが文書に挿入されます。

キー定義に href が割り当てられている場合、テキストの挿入先のエレメントはリンクエレメントになります。href が割り当てられていない場合は、xref などのリンクエレメントにもリンクは含まれません。このリンクの動作は、キー定義を参照するエレメントにコンテンツが含まれており、テキストの挿入には使用できないような場合にも適用されます。たとえば、次のエレメントが上記のキー定義を参照している場合を考えてみます。

この場合、キー参照によってエレメントがリンクエレメントになるだけで、文章をパブリッシングしてもテキストがキー定義に挿入されません。

キー定義から挿入されるテキストは、次の優先順位で決まります。

たとえば、次のキー定義には、テキスト挿入の可能な複数の領域内のテキストが含まれています。

この場合、キー参照のために挿入されるテキストは keyword エレメントのコンテンツになります。こちらの方が navtitle 属性のコンテンツよりも優先順位が高いからです。

次のエレメントはテキスト挿入の特殊ケースです。

link エレメントにはテキストは直接含まれません。このエレメントにはオプションで linktext および desc エレメントが含まれ、これらにテキストを含むことができます。この場合、キー定義の topicmeta エレメント内に linktext および desc エレメントがある場合、文書のパブリッシング時にこれらのエレメントが link エレメントに挿入されます。

image エレメントには、画像のテキスト説明を提供する alt エレメントが含まれます。空の image エレメントに、テキスト挿入用のテキストを含むキー定義へのキー参照がある場合、パブリッシング時には、そのテキストが image に alt エレメントとして挿入されます。

longdescref などの一部の DITA エレメントには keyref 属性が含まれますが、テキストコンテンツは許可されていません。これらのエレメントは、キー参照によるテキストの挿入には使用できません。

Arbortext Editor ユーザーインタフェースでは、キー参照によるテキストの挿入をサポートするために、次の機能が提供されています。

• 「キー参照情報」ダイアログボックスには、キー定義で指定されているテキストコンテンツ (マークアップを含む) を表示する「テキスト」オプションが表示されます。

• 「キー参照の挿入」ダイアログボックスには、「リソース」列にキー定義のテキストコンテンツ (マークアップを含む) が表示されます。

さらに、ditatextkeyrefs アドバンス環境設定が on に設定されている場合、キー参照を許可するリンクでないエレメントが「挿入」ドロップダウンリストに表示されます。

これは、DITA 文書のデフォルトのスタイルシート内のリンクでないエレメントに対してのみサポートされている機能です。キー参照名が表示されるのは、Arbortext Editor で文書を編集しているときのみです。文書のパブリッシング時には表示されません。

トピック参照にキー参照が含まれている場合、topicmeta エレメント内の情報の一部がキー定義内の同様の情報と競合する可能性があります。topicref エレメントには、キー定義として機能する topicmeta エレメントが含まれています。topicref の topicmeta コンテンツをキー参照および参照されるキー定義とマージするときには、次の規則に従います。