Learning DITA

Free DITA training

Free DITA training

Adding more advanced elements

Here are some more common advanced elements in DITA:

<section>

The element that divides the body of a topic into subsections with individual titles. The <section> element can contain a <title> element to give it a heading, along with most of the same elements allowed inside the <conbody> element. However, the <section> element cannot contain other <section> elements and can only be followed by another <section> element, an <example> element, or a <conbodydiv> element.

Note:

If you find that you are adding many sections or sections of substantial length to a topic, make each of those sections into its own topic instead so that you can reuse the information more easily.

<draft-comment>

The element that lets you insert comments and questions into the content while it is being developed. By default, the <draft-comment> element is hidden in the final output, so you can render output without deleting all draft comments. (You have to decide whether you’re willing to risk it, though!)

<required-cleanup>

The element that lets you wrap content that is tagged incorrectly and needs to be fixed. By default, any content inside the <required-cleanup> element is hidden in output.
Practice
  1. Continue using the file lesson4/l_concept_advanced_start.dita to add each of these elements to your example file.
    Video: Adding a section in DITA
  2. After the <lq> element, add a <section> element as shown in the following example:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="concept_advanced">
    <title>Writing about ducks</title>
    <conbody>
    ...
    </lq>
    <section>
    </section>
    </conbody>
    </concept>
    In the example you added, you created a subsection of the “Writing about ducks” topic.
  3. Inside the <section> element, add <title> and <p> elements and add content to them as shown in the following example:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="concept_advanced">
    <title>Writing about ducks</title>
    <conbody>
    ...
    <section>
    <title>Sharing your duck database</title>
    <p>Export your duck database as HTML output to make it easy to share on your website. 
    You can also offer your database to users as a download.</p>
    </section>
    </conbody>
    </concept>
    Only one <title> element is allowed inside the <concept> element where a title already exists. However, by adding a <section> element, you are able to have multiple subtitles in your concept topic. Like the <conbody> element, each <section> element can only contain one <title> element.
    A <section> element can contain all the same body elements as a <conbody>, with the exception of another <section> (that is, you cannot nest <section> elements inside each other).
  4. After the <p> element in the new section, add a <draft-comment> element and add content to it as shown in the following example:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="concept_advanced">
    <conbody>
    ...
    </p>
    <draft-comment>Are you sure you want to offer a download?</draft-comment>
    ...
    </conbody>
    </concept>
    In the example you added, you are telling other authors who may work on this topic to rethink the decision to offer a download.
  5. After the <section> element, add a <required-cleanup> element and at content to it as shown in the following example:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    <concept id="concept_advanced">

    <conbody>
    ...
    </section>
    <required-cleanup>
    <p>Consider giving users the option to send feedback or suggested entries for your 
    duck database.</p>
    </required-cleanup>
    </conbody>
    </concept>

    In this example, you have surrounded the <p> element with the <required-cleanup> element to indicate that someone must move it to a valid position (such as inside the <section> element) or re-tag it with a valid element (such as the <example> element). Otherwise, the final output will not display the text inside the <p> element.
  6. Check your file lesson4/l_concept_advanced_start.dita against the sample file l_concept_advanced.dita.
Practice
  1. Open the file lesson4/l_concept_advanced_exercise_start.dita and use it to convert the following untagged content into DITA:

    Source: Content Strategy 101

  2. Check your file lesson4/l_concept_advanced_start.dita against the sample file lesson4/l_concept_advanced_exercise.dita.
Contributors