Home
DITA map files
DITA map vocabulary
The href attribute in a topic references
A topic reference (topicref) in a ditamap references the topic (or other resource) to be included in the output publication through the href attribute. The value of the href attribute must conform to the standard URI format.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
- Purpose of ditamap files
  DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.
- Topic manifest
  Any topics referenced anywhere in the ditamap will be processed into the output publication.
- Topic hierarchy
  In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.
- Relationship tables
  Relationship tables are used to store linking relationships between topics in a collection in the ditamap, rather than in individual topics. Linking relationships are defined in a table-like structure, with rows in the table determining which topics are linked to which.
- Linking relationships
  DITA encourages the linking relationships to be stored outside the topic content. Links can be generated from topic hierarchies, relationship tables, and related-links section links.
- Inheritance and cascades in ditamaps
  Properties in ditamaps sometimes cascade from parent elements to child elements. Some values in ditamaps also override the equivalent values in referenced topics.
- Embedded (or nested) ditamaps
  The technique of using embedded, or nested, ditamaps can make it easier to manage documents by separating complex collections of topics into a number of smaller, simpler collections.
- DITA map vocabulary
  - The topicref element
    The basic building block of ditamap files is the topic reference (topicref) element.
  - The href attribute in a topic references
    A topic reference (topicref) in a ditamap references the topic (or other resource) to be included in the output publication through the href attribute. The value of the href attribute must conform to the standard URI format.
  - The topichead element
    The topichead element in the ditamap provides a title-only node in the hierarchy, into which normal topic references are nested. Although technically valid, this element should not be used because it results in inconsistent output.
  - The navref element
    The navref element is a specialist element used when constructing dynamically-merged modular Help systems.
  - The copy-to attribute
    The copy-to attribute of the topicref element is used in the unusual situation where you need to create two copies of the same topic in the output, and to link to each copy of the output topic separately. The value of the attribute is the file name of the duplicate.
  - The chunk attribute
    The chunk attribute can control the way output files are generated during the publishing process. Most chunk attribute values apply only to composite topics, which should be avoided. The to-content value is used to generate a single output topic from multiple DITA source topics.
  - Non-DITA topic references
    A ditamap can include references to non-DITA resources, such as PDF documents, spreadsheet files, presentation files, online tutorials, HTML files, and Internet addresses. The topicref element is used for these references, with format and scope attributes describing the type of resource.
  - Dangling topicrefs
    If a ditamap includes a reference to a topic that does not exist, the publishing process will generate output with a broken link. It will not gracefully omit the reference. You should therefore take care to avoid these dangling topicref.
- The bookmap feature
  Bookmaps are a specialisation of the base DITA map information type. Like ditamaps, bookmaps are containers for structure and context metadata, and do not contain any content. Bookmaps are used to describe page layout publishing outputs such as books, articles, manuals and research papers. They contain information structures that are specific to linear publications, such as tables of figures, title pages, chapters, sections and parts.
Syntax and mark-up
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

The href attribute in a topic references

A topic reference (topicref) in a ditamap references the topic (or other resource) to be included in the output publication through the href attribute. The value of the href attribute must conform to the standard URI format.

Topic reference (topicref) elements usually reference a DITA topic, but can also reference external resources such as Web sites. The resources being referenced in topicref element are specified in the href attribute.

A URI, or Uniform Resource Indicator, is a standard for referencing resources on the Internet. The similar term URL, or Uniform Resource Locator, means a specific type of URI where the location and the means of retrieving the resource are both incorporated in the address. For example, the URL http://store.scriptorium.com/items/Books/list.htm nominates the address of the resource and the protocol to use to retrieve it (in this case, http). In general, however, most people use the terms interchangeably!

Files on a file server or network drive on a local network can be referenced using the URI convention. Most DITA authoring tools will let you browse for the resource you want to reference, and then format the address in the correct UNC format. For example, the address of a file on a network server must be prefixed with the protocol smb://.

You must use (forward) slash characters for path separators. Do not use backslashes. Such file references are URIs in DITA, not file paths. The backslash is an illegal character in URIs. When referencing resources on a network server, prefix the UNC path with smb://.

You cannot use an ampersand (&) character in an href attribute. If the URL being referenced contains an ampersand character, the & character escape should be used to indicate that character.