1. The structure of the <topic> element

Remember
Remember
A <topic> element must always be given an ID. Use the @id attribute to specify it.
The structure of the <topic> Opens in new window element is very simple:
  1. A <title> Opens in new window element.
  2. An optional <shortdesc> Opens in new window or <abstract> Opens in new window element.
    The <shortdesc> element is longer and more descriptive than the <title> element. However, it is recommended to keep it short, approximately one paragraph long, because the contents of this element are often used during navigation (e.g. to generate a detailed table of contents).
    The <abstract> element is intended to contain more information than the <shortdesc> element.
  3. A <body> Opens in new window element(1).
  4. An optional <related-links> Opens in new window element.
    This is a kind of ``See Also'' section containing a list of <link> Opens in new window elements. Topics being generally short, this section stands out clearly after the body of a topic. That's why it is often preferred to spreading links inside the body of a topic.
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
<topic id="docbook_or_dita">
  <title>DITA or DocBook?</title>

  <shortdesc>Both DITA and DocBook are both mature, feature rich, document types,
  so which one to choose?</shortdesc>

  <body>
    <p>DocBook 5 is a mature document type. It is well-documented (DocBook:
    The Definitive Guide, DocBook XSL: The Complete Guide), featuring decent
    XSL stylesheets allowing conversion to a variety of formats, based on the
    best schema technologies: RELAX NG and Schematron.</p>

    <p>DITA concepts (topics, maps, specialization, etc) have an immediate
    appeal to the technical writer, making this document type more attractive
    than DocBook. However the DocBook vocabulary is comprehensive and very
    well thought out. So choose DITA if its technical vocabulary is
    sufficiently expressive for your needs or if, anyway, you intend to
    specialize DITA.</p>
  </body>

  <related-links>
    <link format="html" href="http://www.docbook.org/" scope="external">
      <linktext>DocBook 5</linktext>
    </link>

    <link format="html"
          href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita"
          scope="external">
      <linktext>DITA</linktext>
    </link>
  </related-links>
</topic>
The above example is rendered as follows:
 (1) The <body> element is optional too. However creating a <topic> element having no <body> child element is mainly a trick which is more simply implemented by adding a <topichead> Opens in new window to a map.