Home
Content re-use
Re-use practices
Valid referencing elements
When using a conref in a topic to transclude text from another topic, the referencing element must be valid DITA XML.

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
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
- Content re-use definition
  Content re-use is a means of improving efficiency by eliminating repetition of phrases, blocks of text, topics, and even collections of topics.
- Re-use and the DITA Maturity Model
  Content re-use is one of the features that you should adopt early in your move from style-based authoring to structured authoring with DITA.
- The content reference (conref) attribute
  The conref feature allows DITA content to be used in any number of different places in a collection. The conref attribute in a referencing topic specifies the source topic and the element within that topic to re-use.
- Re-use practices
  - Writing for re-use
    You should embrace a style or method of writing that produces content suitable for re-use. This method includes an aim to minimise context.
  - Re-use guidelines
    Re-use guidelines can help simplify the practice of writing for re-use.
  - Valid referencing elements
    When using a conref in a topic to transclude text from another topic, the referencing element must be valid DITA XML.
  - The -dita-use-conref-target attribute value
    A special attribute value of -dita-use-conref-target can be used to force the attribute value of the source of a conref to be used in the referencing element.
  - Re-using content from different elements
    When re-using content through the conref feature, the referenced element type must match the referencing element type.
  - Nested content references
    Content references can be nested inside other content references.
- Variables
- Organising re-use topics and elements
- Embedded topics and ditamaps
  The ditamap is a powerful tool for re-using topics in different output publications. Topics can also be re-used using ditabase topics, but you should avoid this technique.
- Advanced conref principles
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.

Valid referencing elements

When using a conref in a topic to transclude text from another topic, the referencing element must be valid DITA XML.

Conref transclusions involve two elements: the referencing element and the referenced element. The referencing element is the element that will be re-using the content in the referenced element (the source of the re-usable content).

When the element being transcluded requires particular attributes or child elements, then these attributes and elements must also be included in the referencing element code.

For example, a step element must contain at least one cmd element. Therefore, the following mark-up would be invalid DITA because the cmd element is missing.

<step conref="t_starting.dita#t120/sec_code" />

Instead, a dummy cmd element must be included for the mark-up to be valid, as shown in the following.

<step conref="t_starting.dita#t120/sec_code"><cmd /></step>

If an attribute is mandatory in a transcluded element, such at the tmtype attribute in the trademark (tm) element, the referencing element must include the attribute. However, a special attribute value of -dita-use-conref-target can be used to maintain the validity of the element, and specify that the referenced source element's attributes be used in the transclusion.

The mark-up of a referencing element with a mandatory attribute would therefore follow the pattern in the example:

<tm conref="conref_source.dita#names12/var_suparu" 
 tmtype="-dita-use-conref-target" />

If you are using constraints, a feature introduced in DITA 1.2, you must take care to avoid conreffing elements from an unconstrained topic to a constrained topic. (In general, referencing an unconstrained source topic element from a constrained topic will only work if the constraint type is marked as weak, not strict.)