DITA Primer (Learn the DITA basics)

Concept <concept>

The <concept> element contains an answer to a “what is” question. It provides background information that a user must know to successfully work with a product.

A concept explains and teaches ideas to help users build on experience and knowledge they may already have before using a product or performing a task. In this capacity, they are one of the first information types a user is exposed to.

The concept introduces the system, solution, process, or characteristics and provides background information the user should know before starting a task or exploring a reference. Features and benefits of the product would be described in the concept and more detailed information is usually found here.

A concept is focused on providing information on the technology, user concerns, information concerning decisions that may need to be made, background information, product overview, or relationships between products.

The concept contains many elements including a single title, an optional short description, one or more paragraphs, index entries, lists, tables, figures or images, sections and examples, and more.

Element representation:

<concept>

Markup example:

<concept id="c_saving">

<title>Why Save Files</title>

<conbody>

<p>Saving files is an easy way to store content for later retrieval.</p>

</conbody>

</concept>

Display example:

Reference <reference>

The <reference> element contains information that needs to be looked up for technical information. This is usually done by creating specific sections and populating them with concise information.

A reference is generally read by a user only when specific technical information is required, usually while doing a specific job. The reference provides the facts without background information or procedural steps. Any reference may be heavily linked to other related reference materials.

Element representation:

<reference>

Markup example:

<reference id="r_saving">

<title>Saving Files to Servers</title>

<refbody>

<section>

<p>Use the syntax //server/path/file.ext to save to a server. Incorrect syntax results in file corruption.</p>

</section>

</refbody>

</reference>

Display example:

Task <task>

The <task> element contains a procedure. This element provides instructions related to addressing how to do a specific thing and the order of steps to follow.

The purpose of a task is to tell the user how to accomplish a specific set of procedures to achieve a goal. It is often read while a user is performing a specific task and should provide enough information to guide the user to a logical conclusion.

Tasks provide detailed, step-by-step instructions and provide context and examples as required. They may have explicit prerequisites or postrequisites that must be performed by the user. Within the task, there are usually multiple single-step procedures to follow. Each step may be made up of many information including an explicit command (a call to action) and related supporting information.

Element representation:

<task>

Markup example:

<task id="t_saving">

<title>How to Save Files</title>

<taskbody>

<steps>

<step>

<cmd>Click the <uicontrol>Save</uicontrol> icon</cmd>

</step>

</steps>

</taskbody>

</task>

Display example:

Commonly used elements

While DITA provides numerous elements, these topics address only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Title <title>

The <title> element is a heading or label for many elements including topic, concept, reference, task, section, example, table, and so on.

Element representation:

<title>

Markup example:

<title>Why Save Files</title>

Display example:

Short description <shortdesc>

The <shortdesc> element represents the purpose of the content that follows. A <shortdesc> element may also be used as a link preview and when returning search results. The short description should be a concise statement that provides a summary of the topic.

Within a concept, the short description answers a “what is this?” question. This may simply be a key term or idea, and a related basic definition.

Within a task, the short description answers a “what is the purpose of this task?” or “when should this task be performed?” question with a brief overview of the task.

Within a reference, the short description addresses “technically this is” type of information with a brief statement about the technical content to follow.

As a generalization, the short description is likely no more than 1 to 2 sentences and usually no more than 20 or 30 words. It is not a lead-in paragraph.

Element representation:

<shortdesc>

Markup example:

<shortdesc>Used to provide a brief introduction to the topic and often used in links, summary documents, and search results.</shortdesc>

Display example:

Paragraph <p>

The <p> element identifies a string of text that has a single main idea.

Element representation:

<p>

Markup example:

<p>Saving files is an easy way to store content for later retrieval.</p>

Display example:

Note <note>

The <note> element identifies content that appears in a different format from the default of a document and draws attention to a point.

Element representation:

<note>

Markup example:

<note>Failure to shut down the device before opening the containment compartment can result in radiation leakage.</note>

Display example:

Short quotation <q>

The <q> element identifies a short string of text that is a quotation from another source and is usually treated as an inline element, similar to a character range.

Element representation:

<q>

Markup example:

<p>Yogi Berra said <q>It ain't over till it's over</q> close to the end.</p>

Display example:

Long quotation <lq>

The <lq> element identifies a longer string of text that is a quotation from another source and is usually treated as a standalone element, similar to a paragraph.

Element representation:

<lq>

Markup example:

<p>Napoleon Bonaparte has said: <lq>If I always appear prepared, it is because before entering an undertaking, I have meditated long and have foreseen what might occur. It is not genius where reveals to me suddenly and secretly what I should do in circumstances unexpected by others; it is thought and preparation.</lq></p>

Display example:

Index entries <indexterm>

The <indexterm> element represents content that is not displayed in the current topic, but rather in a generated, sorted document.

Element representation:

<indexterm>

Markup example:

<p>To open files you must have access to either a <indexterm>server </indexterm> server or a local drive on a <indexterm>workstation</indexterm> workstation where files have been saved.</p>

Display example:

Lists: <ul> and <ol>

While DITA provides numerous list-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Unordered List <ul>

The <ul> element identifies a collection of items in which the order is not relevant.

Element representation:

<ul>

Markup example:

<p>Assorted breakfast items are available including:

<ul>

<li>Waffles, pancakes or french toast</li>

<li>Assorted meats and cheeses</li>

<li>Fresh fruit (pineapple, grapes, oranges, apples and more)</li>

<li>Coffee, tea</li>

</ul>

</p>

Display example:

Ordered List <ol>

The <ol> element identifies a collection of items in which the order is relevant.

Element representation:

<ol>

Markup example:

<p>After accessing our ftp server:

<ol>

<li>Agree to the licensing terms</li>

<li>Download the software</li>

</ol>

</p>

Display example:

List Item <li>

The <li> element contains content that has a single main idea within a list. If a <li> element is contained in an <ol> element, the <li> element is usually displayed as a numbered list (using traditional numbering, roman numerals, or alphabetical characters in order). If the <li> element is contained in a <ul> element, the <li> element is usually displayed as a bullet or dash.

Element representation:

<li>

Markup example:

<p>After accessing our ftp server:

<ol>

<li>Agree to the licensing terms</li>

<li>Download the software</li>

</ol>

</p>

Display example:

Definition lists <dl>

While DITA provides numerous definition list-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Definition list <dl>

The <dl> element builds a list of terms and definitions.

Element representation:

<dl>

Markup example:

<dl>

<dlentry>

<dt>XML</dt><dd>eXtensible Markup Language</dd>

</dlentry>

<dlentry>

<dt>CSS</dt><dd>Cascading Style Sheet</dd>

</dlentry>

<dlentry>

<dt>HTML</dt><dd>HyperText Markup Language</dd>

</dlentry>

</dl>

Display example:

Definition list entry <dlentry>

The <dlentry> element creates a single item within a definition list.

Element representation:

<dlentry>

Markup example:

<dl>

<dlentry>

<dt>…</dt><dd>…</dd>

</dlentry>

<dlentry>

…

</dlentry>

</dl>

Definition term <dt>

The <dt> element identifies the content that the entry relates to.

Element representation:

<dt>

Markup example:

<dl>

<dlentry>

<dt>XML</dt><dd>…</dd>

…

</dl>

Definition description <dd>

The <dd> element expands on the meaning of the term. Element representation:

<dd>

Markup example:

<dl>

<dlentry>

<dt>…</dt><dd>eXtensible Markup Language</dd>

</dlentry>

…

</dl>

Table <table>

While DITA provides numerous table-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

The <table> element organizes a set of information into a gridlike construct. This allows the representation to be displayed in a grid-like fashion with content spanning rows or columns. An optional title can be included to further identify the table.

Element representation:

<table>

Markup example:

<table>

<title>File formats</title>

<tgroup cols="2">

<colspec colnum="1" colname="col1" colwidth="1.00*"/>

<colspec colnum="2" colname="col2" colwidth="3.00*"/>

<thead>

<row>

<entry colname="col1">Extension</entry>

<entry colname="col2">Definition</entry>

</row>

</thead>

<tbody>

<row>

<entry colname="col1">.xml</entry>

<entry colname="col2">eXtensible Markup Language</entry>

</row>

<row>

<entry colname="col1">.html</entry>

<entry colname="col2">Hyper Text Markup Language</entry>

</row>

…

</tbody>

</tgroup>

</table>

Display example:

Column specifications <colspec>

The <colspec> element organizes the columns of a table including the name of the column and information associated with the column and cells within it. This element does not have to be modified by the user.

Element representation:

<colspec>

Markup example:

<table>

<title>File formats</title>

<tgroup cols="2">

<colspec colnum="1" colname="col1" colwidth="1.00*"/>

<colspec colnum="2" colname="col2" colwidth="3.00*"/>

…

</tgroup>

</table>

Table group <tgroup>

The <tgroup> element organizes the elements within a table including the columns, rows, headers, and the body of the table.

Element representation:

<tgroup>

Markup example:

<table>

<title>File formats</title>

<tgroup cols="2">

…

</tgroup>

</table>

Table header <thead>

The <thead> element organizes the elements within the header of the table. Element representation:

<thead>

Markup example:

<thead>

<row>

<entry colname="col1">Extension</entry>

<entry colname="col2">Definition</entry>

</row>

</thead>

Table body <tbody>

The <tbody> element organizes the elements within the body of the table. Element representation:

<tbody>

Markup example:

<tbody> … </tbody>

Table row <trow>

The <trow> element organizes the elements within the rows of the table. Element representation:

<row>

Markup example:

<row>

<entry colname="col1">.xml</entry>

<entry colname="col2">eXtensible Markup Language</entry>

</row>

Table entry or table cell <entry>

The <entry> element organizes the elements within one cell of the table. Element representation:

<entry>

Markup example:

<row>

<entry colname="col1">.xml</entry>

<entry colname="col2">eXtensible Markup Language</entry>

</row>

Figure <fig>

The <fig> element contains an image and an optional title that acts as a figure caption.

Element representation:

<fig>

Markup example:

<fig>

<title>Windows Run dialog</title>

<image href="run.png" />

</fig>

Display example:

Image <image>

The <image> element displays an image and may be displayed on its own line (often the default for large images) or inline (often the default for an icon or button).

Element representation:

<image>

Markup example:

<p>Click <image placement="inline" href="ok.jpg" /> to proceed.</p>

Display example:

Section <section>

The <section> element represents a collection of organized information. It represents subsets of content that are related to a larger topic and are treated as siblings to each other. An optional title may be used.

Element representation:

<section>

Markup example:

<section>

<title>Saving to servers</title>

<p>Use the syntax //server/path/file.ext to save to a server. Incorrect syntax results in file corruption.</p>…</section>

<section> … </section>

Display example:

Example <example>

The <example> element represents a sample to further illustrate a topic. An example is otherwise identical to a <section> element.

Element representation:

<example>

Markup example:

<example>

<title>Online help</title>

…

</example>

Display example:

Reference syntax <refsyn>

The <refsyn> element represents syntax content such as an API’s signature. It contains a brief description of the subject’s interface or high-level structure. This may then be further defined following the reference syntax.

Element representation:

<refsyn>

Markup example:

<refbody><refsyn>extern LIBBEM_API int bem_logon(bem_handle_t *, char *, char *, char **);</refsyn></refbody>

Display example:

Properties <properties>

The <properties> element represents a list of properties for a topic. This includes the type, value, and description. It is generally represented in a table-like format.

Element representation:

<properties>

Markup example:

<refbody>

<properties>

<prophead>

<proptypehd>Type</proptypehd>

<propvaluehd>Value</propvaluehd>

<propdeschd>Description</propdeschd>

</prophead>

<property>

<proptype>RGB</proptype>

<propvalue>0,0,0</propvalue>

<propdesc>Set color using a red, green, blue color model.</propdesc></property> … </properties>

</refbody>

Display example:

Task body elements <taskbody>

While DITA provides numerous task body-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

The <taskbody> element organizes a set of information into task-specific constructs. This allows the <taskbody> element to have a specific flow of information to guide the user through a set of procedural steps.

Element representation:

<taskbody>

Markup example:

<taskbody>

<steps>

<step>

<cmd>Click the <uicontrol>Save</uicontrol> icon</cmd>

</step>

</steps>

</taskbody>

Display example:

However, far more complex tasks can be created which incorporate many elements.

Task prerequisite <prereq>

The <prereq> element informs the user of specific things to do before starting the task.

Element representation:

<prereq>

Markup example:

<taskbody>

<prereq>You must have an XML editor installed.</prereq> … </taskbody>

Display example:

Task steps <steps>

The <steps> element contains the main set of procedural information related to a task.

Element representation:

<steps>

Markup example:

<steps>

<step>…</step>

<step>…</step>

…

</steps>

Task step <step>

The <step> element contains a specific action that the user must perform to accomplish a task. It contains a minimum of one command.

Element representation:

<step>

Markup example:

<steps>

<step>

<cmd>Open an XML file in your editing software.</cmd>

</step>

</steps>

Step command <cmd>

The <cmd> element provides an active voice instruction to the user that is usually a single sentence.

Element representation:

<cmd>

Markup example:

<step>

<cmd>Open an XML file in your editing software.</cmd>

</step>

Display example:

Information <info>

The <info> element provides information about the command.

Element representation:

<info>

Markup example:

<step>

<cmd>…</cmd>

<info>The filename can be any combination of upper or lowercase letters as well as numbers and underscores.</info>

</step>

Display example:

Step result <stepresult>

The <stepresult> element provides feedback to the user on the expected result of a specific command.

Element representation:

<stepresult>

Markup example:

<step>

<cmd>…</cmd>

<stepresult>The XML file is displayed.</stepresult></step>

Display example:

Substeps <substeps>

The <substeps> element provides additional steps that must be taken within a major step. The output is usually the same as a nested list in appearance. A subset contains all the same element options as a step, except for further substeps.

Element representation:

<substeps>

Markup example:

<step>

<cmd>Save the file.</cmd>

<substeps>

<substep><cmd>Select File.</cmd></substep>

<substep><cmd>Select Save.</cmd></substep>

</substeps>

</step>

Display example:

Step choices <choices>

The <choices> element provides a selection that has more than one option. Element representation:

<choices>

Markup example:

<step>

<cmd>Save the file.</cmd>

<choices>

<choice>Click the Save icon.</choice>

<choice>Press Ctrl+s.</choice>

</choices>

</step>

Display example:

Step choice tables <choicetable>

The <choicetable> element presents table-based choices, which usually include an option and a related description.

Element representation:

<choicetable>

Markup example:

<step>

<cmd>Choose an extension.</cmd>

<choicetable>

<chhead>

<choptionhd>Option</choptionhd>

<chdeschd>Description</chdeschd>

</chhead>

<chrow>

<choption>XML</choption>

<chdesc>eXtensible Markup Language</chdesc>

</chrow>

<chrow><choption>HTML</choption>

<chdesc>HyperText Markup Language</chdesc>

</chrow>

</choicetable>

</step>

Display example:

Step example <stepxmp>

The <stepxmp> element provides a sample of what the step involves. Element representation:

<stepxmp>

Markup example:

<step>

<cmd>Name the file.</cmd>

<stepxmp>For example, name the file WorkingWithCode.xml.</stepxmp>

</step>

Display example:

Result <result>

The <result> element provides feedback to the user on the expected result of a overall task upon completion of all steps.

Element representation:

<result>

Markup example:

<taskbody>

<steps>

…

</steps>

<result>The file is stored on the server.</result>

</taskbody>

Display example:

Postrequisite <postreq>

The <postreq> element provides information after a step is completed.

Element representation:

<taskbody>

Markup example:

</steps>

<postreq>Once you have updated the file, ensure that it is checked back into the CMS server and update your job list.</postreq>

</taskbody>

Display example:

Linking in DITA

While DITA provides numerous linking elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Cross-reference <xref>

The <xref> element provides a link to virtually any other element. This includes related locations within the current file, external files, or external links (such as a URL or an email address). The href attribute provides the location to link to.

Whenever possible, the cross reference should remain internal to allow the greatest amount of reuse.

Element representation:

<xref>

Markup example:

<p>Read info on opening: <xref href="c_Opening.xml">Opening Files</xref></p>

<p>Look up info on opening: <xref href="http://www.google.com">Google</xref>.</p>

<p>Print a copy of our quick reference card <xref href="quickref.pdf" format="pdf">Opening Files</xref>.</p>

Display example:

Related links

Unlike cross-references, the related links cannot occur within the body of a topic and cannot target any element. Instead, related links only target other topics or non-topic objects.

Special processing instructions can be applied when related links are output. These may group links together, sort them, or place them in a specific frame of a help system. Related links can also be used with DITA maps as a way to avoid embedding links within topics.

While DITA provides numerous elements for working with related links, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Related links <related-links>

The <related-links> element supports navigation between topics as well as link to external files, or to external links (such as a URL or an email address).

Element representation:

<related-links>

Markup example:

<related-links> … </related-links>

Display example:

Link <link>

The <link> element defines a target for navigation to connect to. It contains an href attribute that identifies the target.

Element representation:

<link>

Markup example:

<link href="c_PrintingFiles.xml”></link>

<link href="http://www.google.com" scope="external" format="html"><linktext>http://www.google.com</linktext></link>

<link href="print/files.pdf"><linktext>print/files.pdf</linktext></link>

Display example:

Link text <linktext>

The <linktext> element provides a string of text to be used when representing a link visually. Normally, though, the destination that a <link> element references contains content that is automatically used.

Element representation:

<linktext>

Markup example:

<link href="http://www.google.com" scope="external" format="html">

<linktext>http://www.google.com</linktext>

</link>

Domain elements

Domain elements support many terms that relate to programming, software, and user interface-specific writing. They also include conventions related to common typographical conventions. A generalization can be made that domain elements relate to the idea of creating specific ranges of structure that are transformed into the equivalent of character range formats.

While DITA provides numerous domain-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Typographical

Typographical elements apply styles such as bold or italic to a range of characters. It is a generally accepted best practice that they are avoided if a semantically specific element can be used instead.

Bold <b>

The <b> element applies bold to a text range. Element representation:

<b>

Markup example:

<p>If possible, <b>avoid</b> typographical elements.</p>

Display example:

Italic <i>

The <i> element applies italics to a text range. Element representation:

<i>

Markup example:

<p>If possible, <i>avoid</i> typographical elements.</p>

Display example:

Underline <u>

The <u> element applies underline to a text range. Element representation:

<u>

Markup example:

<p>If possible, <u>avoid</u> typographical elements.</p>

Display example:

Type text <tt>

The <tt> element applies typetext (usually a monospace font, such as Courier) to a text range.

Element representation:

<tt>

Markup example:

<p>If possible, <tt>avoid</tt> typographical elements.</p>

Display example:

Superscript <sup>

The <sup> element applies superscript to a text range. Element representation:

<sup>

Markup example:

<p>Albert Einstein stated, in 1905, that E=mc² where E is the speed of light, m is the mass, and c is the speed of light in a vacuum.</p>

Display example:

Subscript <sub>

The <sub> element applies subscript to a text range. Element representation:

<sub>

Markup example:

<p>The chemical formula for water is H₂O where H is hydrogen and O is oxygen.</p>

Display example:

Programming elements

The elements related to programming are used to define syntax and samples related to programming languages (HTML, XML, XSL, FO, Java, Python, PHP, C#, ASP, JavaScript, Perl, and so on) and code.

While DITA provides numerous programming-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Code phrase <codeph>

The <codeph> element represents a specific phrase of code (usually displayed as a monospace font, such as Courier) as an inline text component.

Element representation:

<codeph>

Markup example:

<p>Type <codeph>dir</codeph> to list the directory.</p>

Display example:

Codeblock <codeblock>

The <codeblock> element documents a collection of multiple lines of code (usually displayed as a monospace font, such as Courier) as a collection of lines with line endings.

Element representation:

<codeblock>

Markup example:

<p>A variety of commands exist to list directory information:

<codeblock>

dir /s

dir /p

dir /w

dir /s /w /p

</codeblock>

</p>

Display example:

Additional programming elements

A variety of additional elements exist, to support parameters, syntax, operators, delimiters, separators, options, keywords, variables, and API names. However, they are not addressed here. For more detailed information, review the documentation included with the DITA Open Toolkit.

Software elements

The elements related to software are used to document the way that an application is operated.

While DITA provides numerous software-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Message phrase <msgph>

The <msgph> element documents the text of a message that is created by an application.

Element representation:

<msgph>

Markup example:

<p>The phrase <msgph>copy complete</msgph> displays.</p>

Display example:

File path <filepath>

The <filepath> element documents the name and location, including the directory path, of an object on a computer.

Element representation:

<filepath>

Markup example:

<p>The file is in <filepath>c:\</filepath> by default.</p>

Display example:

User input <userinput>

The <userinput> element documents the text a user should input when prompted by an application.

Element representation:

<userinput>

Markup example:

<p>Type <userinput>confirm</userinput> to close the file.</p>

Display example:

Additional software elements

A variety of additional elements exist, to support messages, commands, system outputs, and variables. However, they are not addressed here. For more detailed information, review the documentation included with the DITA Open Toolkit.

User interface

The elements related to user interface are used to document the components that make up an application’s visual appearance.

While DITA provides numerous user interface elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

User interface control <uicontrol>

The <uicontrol> element documents the names of objects in an application. This may include a button or dialog name.

If a menu item is referenced, and only one level of entry is referenced, the <uicontrol> element can be used. However, for nested entries, use the <menucascade> element (for example, File > Close should use the element menucascade, which contains two or more <uicontrol> elements).

Element representation:

<uicontrol>

Markup example:

<p>Click the <uicontrol>Close</uicontrol> icon.</p>

Display example:

Menu cascade <menucascade>

The <menucascade> element documents a set of menu choices that branch off each other.

For nested entries, use the <menucascade> element with the <uicontrol> element (for example, File > Print should use the <menucascade> element, which contains two or more <uicontrol> elements). However, if a menu item is referenced, and only one level of entry is referenced, the <uicontrol> element can be used.

Element representation:

<menucascade>

Markup example:

<p>Select <menucascade><uicontrol>File</uicontrol><uicontrol>Close</uicontrol></menucascade> to close the file.</p>

Display example:

Window title <wintitle>

The <wintitle> element documents the names of windows or dialogs. Element representation:

<wintitle>

Markup example:

<p>The <wintitle>Print</wintitle> dialog is displayed.</p>

Display example:

Additional user interface elements

Many additional elements exist to support shortcuts and screens. However, they are not addressed here. For more detailed information, review the documentation included with the DITA Open Toolkit.

Prolog elements

The elements related to prolog are used to add information to the document being created. This information is generally not displayed in generated output. The metadata may also be used for publishing purposes to identify content that may or may not be published. It may also be used to build a navigation system, customize the index entries, or even to automatically include or exclude specific topics in the published version depending on the permissions granted.

While DITA provides numerous prolog-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Prolog <prolog>

The <prolog> element provides information about the topic.

Element representation:

<prolog>

Markup example:

<prolog>

<author>Vicky Lee</author>

<author>Noah Macleander</author>

<publisher>Publishing Smarter</publisher>

<copyright>

<copyryear year="2007"/>

<copyrholder>Publishing Smarter</copyrholder>

</copyright>

<critdates>

<created date="1999-02-07"/>

<revised modified=”2006-05-16”/>

<revised modified=”2006-10-11”/>

<revised modified="2006-11-02" golive="2007-01-23"/>

</critdates>

<permissions view="entitled"/>

</prolog>

Author <author>

The <author> element provides information about the person or persons who wrote the topic.

Element representation:

<author>

Markup example:

<author>Vicky Lee</author><author>Noah Macleander</author>

Publisher <publisher>

The <publisher> element provides information about the company or person who is responsible for publishing the topic.

Element representation:

<publisher>

Markup example:

<publisher>Publishing Smarter</publisher>

Copyright <copyright>

The <copyright> element provides information about a single copyright entry including copyright years and copyright holder.

Element representation:

<copyright>

Markup example:

<copyright> … </copyright>

Copyright year <copyryear>

The <copyryear> element provides the year that the copyright is specific to. Element representation:

<copyryear>

Markup example:

<copyryear year="2007"/>

Copyright holder <copyrholder>

The <copyrightholder> element provides information about the company or person who holds the legal rights of a topic and its content.

Element representation:

<copyright>

Markup example:

<copyrholder>Publishing Smarter</copyrholder>

Critical dates <critdates>

The <critdates> element provides information such as creation date and revision dates.

Element representation:

<critdates>

Markup example:

<critdates> … </critdates>

Creation date <created>

The <created> element provides information about the date a document was first created. This is done through the use of the date, golive, and expiry attributes.

Element representation:

<created>

Markup example:

<created date="1999-02-07"/>

Revision date <revised>

The <revised> element provides information about the date a document was modified. This is done through the use of the modified, golive, and expiry attributes.

Element representation:

<revised>

Markup example:

<revised modified=”2006-10-11”>

<revised modified="2006-11-02" golive="2007-01-23" expiry=”2008-05-16”/>

Permissions <permissions>

The <permissions> element provides information about how a topic is allowed to be accessed by setting the view attribute. Values include: internal, classified, all, and entitled.

Element representation:

<permissions>

Markup example:

<permissions view="entitled"/>

Additional prolog elements

A variety of additional elements exist, to support source, metadata (including audience, category, keywords, prodinfo [including prodname, vrmlist (including vrm), brand, series, platform, prognum, featnum, and component], and othermeta), and resourceid. However, they are not addressed here. For more detailed information, review the documentation included with the DITA Open Toolkit.

Common attributes and values

Attributes are used to add information to the document being created. The metadata may be used for many purposes, including the appearance and placement of content, the creation and management of navigational links, the flagging of information for specific publishing or distribution purposes, the building of maps, translation, and more.

While DITA provides numerous attributes and values related to elements, this topic addresses only some of the common attributes that a new user should initially be aware of. For more detailed information, review, the documentation included with the DITA Open Toolkit.

Display attributes <display-atts>

Display-related attributes are used primarily for formatting the appearance of content.

Scale <scale>

An optional attribute used to increase or decrease the font size by using a fixed and predefined value.

Attribute options:

(50 | 60 | 70 | 80 | 90 | 100 | 110 | 120 | 140 | 160 | 180 | 200)

Markup example:

<codeblock scale="90">

Frame or border <frame>

An optional attribute used to create a border around an element by using a fixed and predefined value.

Attribute options:

(top | bottom | topbot | all | sides | none)

Markup example:

<codeblock frame="all">

Expanse or placement <expanse>

An optional attribute used to horizontally place an element by using a fixed and predefined value.

Attribute options:

(page | column | textline)

Markup example:

<codeblock expanse=”column">

Identification attributes <id-atts>

ID-related attributes are used primarily for naming and referencing elements.

Unique identifier <id>

An optional attribute used to uniquely identify an element. While optional, the best practice is to define a value for at least topic, concept, reference, and task elements.

Attribute options:

unique value

Markup example:

<concept id="saving">

conref

An optional attribute used to reference to a uniquely identified element. While optional, the best practice is generally to define a value for topic, concept, reference, and task elements.

Attribute options:

unique value

Markup example:

<concept id="saving">

Selection attributes <select-atts>

Selection-related attributes are used to flag and filter elements based on many criteria.

Platform <platform>

Indicates operating system and hardware that is applicable to the element.

Attribute options:

text string

Markup example:

<concept platform=”windows”>

Product <product>

Indicates the product name that is applicable to the element.

Attribute options:

text string

Markup example:

<concept product="Widget-O-Matic2K">

Audience <audience>

Indicates the audience that is applicable to the element.

Attribute options:

text string

Markup example:

<concept audience="developers">

Importance <importance>

Indicates the priority that is applicable to the element.

Attribute options:

obsolete | deprecated | optional | default | low | normal | high | recommended | required | urgent

Markup example:

<concept importance="low">

Revision <rev>

Indicates the revision or version level that is applicable to the element.

Attribute options:

text string

Markup example:

<concept rev="2.0">

Status <status>

Indicates the state or modification that is applicable to the element.

Attribute options:

new | changed | deleted | unchanged

Markup example:

<concept status="new">

Additional attributes

A variety of additional attributes exist including univ-atts, rel-atts, topicref-atts, and topicref-atts-no-toc. However, they are not addressed here. For more detailed information, review the documentation included with the DITA Open Toolkit.

Map elements

While DITA provides numerous map-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Map <map>

The <map> element provides information about the relationships between topics. The map may contain numerous topics, nested topics, links between topics, and other information to organize content. It could be compared in general terms to a book or a master document that links to other documents and defines relationships between them.

A map is generally used to manage multiple topics and combine references between them. Content is organized in a hierarchy that forms the basic structure of the map and organizes topics into relationships based on this hierarchy.

The relationship in the map can be represented as navigational for tables of contents or for the purpose of developing related links. This relationship can be used to generate a table of contents, to combine topics into a help or PDF deliverable, and to manage content regarding links between topics. The DITA map can then be published as required.

Maps are organizational objects in DITA. They bring together many topics to help create a finished product. The map is then used to assemble the topics into various deliverables based on product lines or releases or other criteria related to publishing.

Since topics are written as standalone units of information, they need a way to be added to a larger deliverable for true functionality of content. A discrete unit of information (the topic) may still be a small part of a final file set. The map would combine topics in a specific order for publishing and this may differ for print (or PDF) output when compared with online (or Help) content. Therefore, multiple maps may be created for multiple types of output.

The representation of the map is a simple XML file. This XML file contains references to specific topics and instructions that are used when processing the map for output.

Element representation:

<map>

Markup example:

<map title="Managing Files">

<topicref href="c_OpeningFiles.xml"/>

…

</map>

Display example:

Topic reference <topicref>

The <topicref> element identifies a topic so that a map can identify the location of a required resource.

Element representation:

<topicref>

Markup example:

<map title="Managing Files">

<topicref href="c_Opening.xml" navtitle="Opening Files"/>

<topicref href="c_Saving.xml" navtitle="Saving Files"/>

<topicref href="c_Closing.xml" navtitle="Closing Files"/>

</map>

Display example:

Relationship table

While DITA provides numerous relationship table-related elements, this topic addresses only some of the common elements that a new user should initially be aware of. For more detailed information, review the documentation included with the DITA Open Toolkit.

Relationship table <reltable>

The <reltable> element builds a set of relationships between topics based on the table model of rows, columns, and cells. Each cell contains one or more <topicref> elements, which are related to other topics in the same row.

Element representation:

<reltable>

Markup example:

<reltable title="Saving Files">

<relheader>

<relcolspec type="task"/>

<relcolspec type="concept"/>

<relcolspec type="reference"/>

</relheader>

<relrow>

<relcell>

<topicref format="dita" href="t_saving.xml"/>

</relcell>

<relcell>

<topicref href="c_saving.xml"/>

<topicref href="c_SavingMultiFormat_withEdits.xml"/>

</relcell>

<relcell>

<topicref href="r_saving.xml"/></relcell>

</relrow>

</reltable>

Display example:

Relationship table header <relheader>

The <relheader> element contains a common heading under which one or more DITA topics are grouped logically.

Element representation:

<relheader>

Markup example:

<relheader>

<relcolspec type="reference"/>

<relcolspec type="concept"/>

<relcolspec type="task"/>

</relheader>

Relationship table row <relrow>

The <relrow> element builds a single row in a relationship table. This row creates a relationship between the elements for linking purposes.

Element representation:

<relrow>

Markup example:

<relrow>

<relcell>

<topicref href="t_Saving.xml" navtitle="Saving Files"/>

</relcell>

<relcell>

…

</relrow>

Relationship table cell <relcell>

The <relcell> element contains one or more DITA topics that are grouped logically under a common heading. By default, the content within a cell does not link to other content in the same cell. Rather, it links to content in related cells.

Element representation:

<relcell>

Markup example:

<relcell><topicref href="t_Saving.xml" navtitle="Saving Files/"></relcell>

Publishing from DITA

To publish content from the DITA specification, at least one standalone topic, or as much as a full collection of topics in a map using <reltable> content, must exist. Depending on the complexity of the content, the finished published file may be as simple as a single PDF file or a standalone Web page. However, a complete set of help documentation, a publication ready for print, or any combination of these can be created.

Publishing a single topic

A single topic can be published to many formats including PDF and HTML Web pages.

Markup example:

<?xml version="1.0"?>

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="c_closing_files">

<title>When Closing Files</title>

<shortdesc>Files which have been opened may be closed and changes saved or discarded.</shortdesc>

<conbody><p>When files are opened and printing or modifications are complete, they need to be closed. This frees up system resources and makes the file available to others who may need to use it.</p></conbody>

</concept>

Publishing a map

A map can be published to many formats including PDF, HTML Web pages, and a compiled help system.

Markup example:

<?xml version="1.0"?>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">

<map id="saving" title="Saving Files">

<topichead navtitle="Concepts">

<topicref href="c_SavingFiles.xml"/></topichead>

<topichead navtitle="Tasks">

<topicref href="t_SavingFiles.xml"/>

<topicref href="t_SavingToNewLocations.xml"/></topichead>

<topichead navtitle="References">

<topicref href="r_SavingToMultipleDevices.xml"/>

<topicref href="r_SavingFiles.xml"/></topichead>

<reltable title="Saving Files">

<relheader><relcolspec type="task" /><relcolspec type="concept" /><relcolspec type="reference" /></relheader>

<relrow>

<relcell><topicref href="t_SavingFiles.xml"/></relcell>

<relcell><topicref href="c_SavingFiles.xml"/></relcell>

<relcell><topicref href="r_SavingToMultipleDevices.xml"/></relcell></relrow>

<relrow>

<relcell><topicref href="t_SavingFiles.xml"/></relcell>

<relcell></relcell>

<relcell><topicref href="r_SavingFiles.xml"/></relcell></relrow>

<relrow><relcell></relcell><relcell></relcell>

<relcell collection-type="family">

<topicref href="r_SavingToMultipleDevices.xml"/>

<topicref href="r_SavingFiles.xml"/>

</relcell></relrow></reltable>

</map>

Display example: