DITA1.2で強化された用語集トピック その2
「DITA 1.2 Feature Description: Glossary and Terminology Specialization」に書かれたベスト・プラクティスに従って、用語集を書いてみました。
【注意】
DITA-OT1.5 M21のPDF出力では、まだkeyrefがサポートされていません。
1用語1ファイルで作成しています。
=== 用語集トピックの書き方の例 ここから ===
contentmanagementsystem.dita
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/glossary.dtd"> <glossentry id="gloss_contentsmanagementsystem" xml:lang="ja-jp"> <glossterm>コンテンツ・マネージメント・システム</glossterm> <glossdef>デジタル・コンテンツの管理を行うシステムの総称。デジタル・コンテンツのリポジトリ(器)を提供するだけのシステムから、デジタル・コンテンツの制作、編集、配信のワークフロー管理機能を持つシステムまで、広いレンジのシステムが存在する。</glossdef> <glossBody> <glossSurfaceForm>コンテンツ・マネージメント・システム(CMS)</glossSurfaceForm> <glossAlt> <glossAbbreviation>CMS</glossAbbreviation> </glossAlt> </glossBody> </glossentry>
contentreference.dita
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/glossary.dtd"> <glossentry id="gloss_contentreference" xml:lang="ja-jp"><glossterm>コンテンツ参照</glossterm> <glossdef>DITAのコンテンツ再利用機能の1つで、conref属性を使ってトピックあるいはマップの一部を再利用する機能のこと。</glossdef> </glossentry>
crossreference.dita
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE glossentry PUBLIC "-//OASIS//DTD DITA Glossary//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/glossary.dtd"> <glossentry id="gloss_crossreference" xml:lang="ja-jp"><glossterm>相互参照</glossterm> <glossdef>あるトピックの中から、同一のトピック内あるいは別のトピック内にある、図表の番号、リスト番号、フットノート番号、セクション・タイトル、トピック・タイトルなどを参照する機能のこと。</glossdef> </glossentry>
=== 用語集トピックの書き方の例 ここまで ===
=== 用語集のためのマップの書き方の例 ここから ===
glossary.ditamap
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/map.dtd"> <map title="DITA Topic Map" xml:lang="ja-jp"> <title>用語集</title> <topichead navtitle="用語集"> <topicref href="dita.dita" keys="wrg_dita"/> <topicref href="ditaopentoolkit.dita" keys="wrg_ditaopentoolkit"/> <topicref href="oasis.dita" keys="wrg_oasis"/> <topicref href="specialization.dita" keys="wrg_specialization"/> <topicref href="topictype.dita" keys="wrg_topictype"/> <topicref href="structualspecialization.dita" keys="wrg_structualspecialization"/> <topicref href="domainspecialization.dita" keys="wrg_domainspecialization"/> <topicref href="classattribute.dita" keys="wrg_classattribute"/> <topicref href="informationmappingsystem.dita" keys="wrg_informationmappingsystem"/> <topicref href="shortdescription.dita" keys="wrg_shortdescription"/> <topicref href="topicmap.dita" keys="wrg_topicmap"/> <topicref href="topicid.dita" keys="wrg_topicid"/> <topicref href="contentsmanagementsystem.dita" keys="wrg_contentsmanagementsystem"/> <topicref href="contentreference.dita" keys="wrg_contentreference"/> <topicref href="crossreference.dita" keys="wrg_crossreference"/> </topichead> </map>
writing_guide.ditamap
<?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="writing_guide" xml:lang="ja-jp"> <title>DITA1.1 ライティング・ガイド</title> <bookmeta> <author>ライティング・ガイド制作部会</author> <prodinfo> <prodname>DITA1.1 ライティング・ガイド</prodname> <vrmlist> <vrm version="00E"/> </vrmlist> </prodinfo> <bookrights> <bookowner> <organization>DITAコンソーシアムジャパン</organization> </bookowner> </bookrights> </bookmeta> <frontmatter> <booklists> <toc/> </booklists> <preface href="preface.dita"/> </frontmatter> <chapter format="ditamap" href="about_dita/about_dita.ditamap" navtitle="DITAについて知っておくべきこと" type="concept"/> <chapter format="ditamap" href="about_general_topic/about_general_topic.ditamap" navtitle="汎用トピックの書き方" type="concept"/> <chapter format="ditamap" href="about_concept_topic/about_concept_topic.ditamap" navtitle="コンセプト・トピックの書き方" type="concept"/> <chapter format="ditamap" href="about_task_topic/about_task_topic.ditamap" navtitle="タスク・トピックの書き方" type="concept"/> <chapter format="ditamap" href="about_reference_topic/about_reference_topic.ditamap" navtitle="リファレンス・トピックの書き方" type="concept"/> <chapter format="ditamap" href="about_topic_body/about_topic_body.ditamap" navtitle="トピック本文を書く" type="concept"/> <chapter format="ditamap" href="about_link/about_link.ditamap" navtitle="リンクを書く" type="concept"/> <chapter format="ditamap" href="about_map/about_map.ditamap" navtitle="マップを書く" type="concept"/> <backmatter> <booklists> <glossarylist> <mapref href="glossary/glossary.ditamap"/> </glossarylist> </booklists> </backmatter> </bookmap>
=== 用語集のためのマップの書き方の例 ここまで ===
=== 用語集を使ったトピック本文の書き方の例 ここから ===
略語がある用語は
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/concept.dtd"> <concept id="topic_id" xml:lang="ja-jp"> <title>トピックIDの指定 @id</title> <shortdesc>すべてのトピックには、トピックを識別するためのトピックID(id属性)を指定しなければいけません。</shortdesc> <prolog> <metadata> <keywords> <indexterm>id属性<index-sort-as>idぞくせい</index-sort-as></indexterm> </keywords> </metadata> </prolog> <conbody> <p>トピックIDは、他のトピックやマップからトピックを参照するときに、トピックを識別する目的で使われます。このため、文書を構成するすべてのトピックを通じて、トピックIDがユニークでなければいけません。なお、トピックIDの値は、大文字と小文字の違いが区別されます。</p> <note type="tip"><abbreviated-form keyref="wrg_contentsmanagementsystem" />を使用している場合、<abbreviated-form keyref="wrg_contentsmanagementsystem" />によってトピックIDが自動付与されることがあります。</note> <section> <title>トピックIDの付与ルール</title> <p>各組織において、トピックIDの付け方にルールを設けるべきです。適切なルールを設けることにより、トピックの執筆者に以下のようなメリットがもたらされます。</p> <ul> <li>トピックIDの付け方に悩まなくて済む</li> <li>トピックIDを調べる手間が省ける</li> <li><term keyref="wrg_contentreference"/>(conref)や<term keyref="wrg_crossreference" />(xref)を書く際のミスを減少できる</li> </ul> <p>ソフトウェアの変数名の付け方に倣って、下記のルールに従ってトピックIDを付与することを推奨します。</p> <ul> <li>英数字およびアンダースコア(_)からなる、アスキー・テキストで指定する</li> <li>英字はすべて小文字とする</li> <li>文字列の先頭は英字あるいはアンダースコア(_)とする</li> </ul> <note type="tip" >DITAからXHTMLを生成すると、ハイパーリンクのリンク先を示すためにトピックIDの値がそのままアンカー名として使われる場合があります。リンクを解決するときに、リンク先のアンカー名の大文字・小文字を区別するかどうかは、Webブラウザによって異なります。したがって、XHTMLのハイパー・リンクのリンク切れを防止するためにも、トピックIDの中の英字は、すべて小文字に統一すべきです。</note> </section> </conbody> </concept>
=== 用語集を使ったトピック本文の書き方の例 ここまで ===
出力結果は、以下のようになります。
用語をクリックすると、用語集のページが表示されます。