• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Learning DITA

Free DITA training

Free DITA training

  • Log in
  • Register
  • Newsletter
  • Profile
  • Privacy
  • Home
  • About
  • Courses
  • News
  • Resources
  • Support the site
  • Contact
  • Recordings

Adding more advanced elements

Posted on 08.30.15

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
  • Gretyl Kinsey, Scriptorium

sidebar

Blog Sidebar

  • Scriptorium logo
    Maximize the value of your content. Read more.
  • Scriptorium logo
    Already in DITA and need support? Contact us.
RSSTwitter

Want to add content? Join the ditatraining GitHub repository.

  • Home
  • Sponsor
  • News
  • Contact
  • Privacy
  • Cookie Policy

Maintained by Scriptorium Publishing

Logo and site presentation © 2015-2023 Scriptorium Publishing. Content based on the open-source DITA training project.

Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}
Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}