リファレンス・トピックの構造

リファレンス・トピック(reference要素)は、タイトル(title要素)、ショート・デスクリプション(shortdesc要素)、プロローグ(prolog要素)、本文(refbody要素)、および関連リンク(related-links要素)から構成されます。これらのトピックを構成する要素のうち、必須なのはタイトルだけです。

リファレンス・トピックの構造を下図に示します。



リファレンス・トピックの構造

リファレンス・トピックの本文(refbody要素)は、柔軟に構成できるようになっています。リファレンス・トピックの本文には、以下の要素を記述することができ、これらの要素はすべて省略可能で、かつ、どんな順番で何回記述しても構いません。ただし、同じ分類の情報を記述するときには、各リファレンス・トピックに含める要素やそれらの並びを統一すべきです。使用する要素やそれらの並びを統一することにより、読者が情報を理解するパターンを作りやすくなります。理解のパターンができると、読者はどこを見れば必要な情報が得られるのか、察しがつくようになります。

refsyn要素
ステートメントやコマンドなどの構文を記述します。
properties要素
引数やオプションといったプロパティ情報の、型、値、および説明の一覧を記述します。
section要素
リファレンス・トピック内での情報の区切りを表すときに使います。section要素の先頭にはタイトルを書けますが、省略しても構いません。
example要素
リファレンス・トピックの中で説明している構文などの記述例を書きます。
table要素
表形式で情報を記述するときに使います。

リファレンス・トピックの記述例

リファレンス・トピックの簡単な記述例を下記に示します。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"http://docs.oasis-open.org/dita/v1.1/OS/dtd/reference.dtd">
<reference id="fo_text_align" xml:lang="ja-jp">
  <title>PDFの本文を均等配置にする</title>
  <shortdesc>行内のテキストの配置を指定するには、text-align属性とtext-align-last属性を指定します。</shortdesc>
  <refbody>
    <refsyn>
      <title>記述例</title>
        <codeblock>&lt;fo:block id="" space-after="0.6em" space-after.optimum="3pt" space-before="0.6em" <b>text-align="justify" text-align-last="left"</b> text-indent="0em" line-height-shift-adjustment="disregard-shifts"&gt;disableRelatedLinks&lt;fo:inline line-height="100%" font-family="MSMincho"&gt;プロパティのデフォルト値は&lt;/fo:inline&gt;no&lt;fo:inline line-height="100%" font-family="MSMincho"&gt;(関連リンクを出力しない)になっています。&lt;/fo:inline&gt;&lt;/fo:block&gt;</codeblock>
    </refsyn>
    <section>
      <title>解説</title>
      <p>PDF本文の、行内のテキストを均等配置にするには、foタグに以下の2つの属性を指定します。</p>
      <simpletable>
        <strow>
          <stentry>text-align="justify"</stentry>
          <stentry>段落内のすべての行を均等配置にする指定</stentry>
        </strow>
        <strow>
          <stentry>text-align-last="left"</stentry>
          <stentry>段落内の最終行を左詰にする指定</stentry>
        </strow>
      </simpletable>
      <p>text-align-last="left"を指定しないと、段落の最後の行まで均等配置されるため、文字間隔が異常に開いてしまいます。</p>
    </section>
  </refbody>
</reference>