conref-file.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
 "concept.dtd">
<concept id="reuse_file" xml:lang="en-us">
        <title>Reuse file</title>
        <shortdesc>This file contains elements used by multiple files in the DITA
                specification.</shortdesc>
        <conbody>
                <section id="section-1">
                        <title>Short descriptions for archSpec topics</title>
                        <!--Also used in "Basic concepts" topic-->
                        <p><ph id="topics-shortdesc">In DITA, a topic is the basic unit of authoring
          and reuse. All DITA topics have the same basic structure: a title and, optionally, a body
          of content. Topics can be generic or more specialized; specialized topics represent more
          specific information types or semantic roles, for example,
            <xmlelement>concept</xmlelement>, <xmlelement>task</xmlelement>, or
            <xmlelement>reference</xmlelement></ph></p>
                        <p><ph id="maps-shortdesc">DITA maps are documents that organize topics and
          other resources into structured collections of information. DITA maps specify hierarchy
          and the relationships among the topics; they also provide the <ph>contexts</ph> in which
          keys are defined and resolved.</ph></p>
                        <p><ph id="information-typing-shortdesc">Information typing is the practice
          of identifying types of topics, such as concept, reference, and task, to clearly
          distinguish between different types of information. Topics that answer different reader
          questions (How do I? What is?) can be categorized with different information types. The
          base information types provided by DITA specializations (for example, technical content,
          machine industry, and learning and training) provide starter sets of information types
          that can be adopted immediately by many technical and business-related
        organizations.</ph></p>
                        <p><ph id="linking-shortdesc">DITA depends heavily on links. The purposes
                                        for which it provides links include defining the content and
                                        organization of publication structures (DITA maps),
                                        topic-to-topic navigation links and cross references, and
                                        reuse of content by reference. All DITA links use the same
                                        addressing mechanisms, either URI-based addresses or
                                        indirect addresses using keys and key references.</ph></p>
                        <p><ph id="addressing-shortdesc" >DITA provides two
          addressing mechanisms. DITA addresses either are direct URI-based addresses, or they are
          indirect key-based addresses. Within DITA documents, individual elements are addressed by
          unique identifiers specified on the <xmlatt>id</xmlatt> attribute. DITA defines two
          fragment-identifier syntaxes; one is the full fragment-identifier syntax, and the other is
          an abbreviated fragment-identifier syntax that can be used when addressing non-topic
          elements from within the same topic.</ph></p>
                        <p><ph id="conref-shortdesc">The DITA <xmlatt>conref</xmlatt>,
            <xmlatt>conkeyref</xmlatt>, <xmlatt>conrefend</xmlatt>, and <xmlatt 
            >conaction</xmlatt> attributes provide mechanisms for reusing content within DITA topics
          or maps. <ph >These mechanisms can be used both to <ph 
              >pull and push</ph> content.</ph></ph></p>
                        <p><ph id="conditional-processing-shortdesc"
          >Conditional processing is the filtering or flagging of
          information based on processing-time
          criteria.<!--Conditional processing, also known as profiling, is the filtering or flagging of information based on processing-time criteria.--><!--Attribute-based profiling, also known as conditional processing or applicability, is the use of classifying metadata that enables the filtering, flagging, searching, indexing, and other processing based on the association of an element with one or more values in a specific classification domain.--></ph></p>
                        <p><ph id="configuration-shortdesc">A document-type shell is an XML grammar
          file that specifies the elements and attributes that are allowed in a DITA document. The
          document-type shell integrates structural modules, domain modules, and <ph rev="2.0"
            >element-configuration modules</ph>. In addition, a document-type shell specifies
          whether and how topics can nest.</ph></p>
                        <p><ph id="specialization-shortdesc">The specialization feature of DITA
          allows for the creation of new element types and attributes that are explicitly and
          formally derived from existing types. This facilitates interchange of conforming DITA
          content and ensures a minimum level of common processing for all DITA content. It also
          allows specialization-aware processors to add specialization-specific processing to
          existing base processing. </ph></p>
                        <p><ph id="contraints-shortdesc">Constraint modules
          <!--define additional constraints for vocabulary modules in order to -->restrict
          content models or attribute lists for specific element types,
          remove certain extension elements from an integrated domain
          module, or replace base element types with domain-provided,
          extension element types.</ph></p>
      <p><ph id="coding-req-topic-type-modules-shortdesc">Topic-type vocabulary modules <term
            outputclass="RFC-2119">MUST</term> conform to additional coding
          requirements for defining <term>default topic nesting</term>. Default topic nesting
          defines whether topics are permitted to nest and what topic types are permitted to
          nest.</ph></p>
      <p><ph id="keys-scopes-and-key-precedence-shortdesc">For purposes of key definition
          precedence, the scope-qualified key definitions from a child scope are considered to occur
          at the location of the scope-defining element within the parent scope.</ph></p>
                </section>

                <section id="section-2">
                        <title>Short descriptions for langRef topics</title>
                        <lines>
                          <!-- Short description for language reference edition topic -->
<ph id="langRef-shortdesc">The language reference portion of the DITA specification contains a topic for each DITA element. The topic defines the element, its inheritance hierarchy, and provides examples of usage. This portion of the DITA specification also includes information about DITA attributes.</ph>
</lines>
                </section>
    <section id="shortdesc-ditavalref">
      <title>Short descriptions for ditavalref metadata elements</title>
      <lines><ph id="shortdesc-dvrKeyscopePrefix">The <xmlelement>dvrKeyscopePrefix</xmlelement> element specifies the prefix to use when constructing the effective key scope names for the map branch that is implied by the ancestor <xmlelement>ditavalref</xmlelement> element.</ph>
<ph id="shortdesc-dvrKeyscopeSuffix">The <xmlelement>dvrKeyscopeSuffix</xmlelement> element specifies the suffix to use when constructing the effective key scope names for the map branch that is implied by the ancestor <xmlelement>ditavalref</xmlelement> element.</ph>
<ph id="shortdesc-dvrResourcePrefix">The <xmlelement>dvrResourcePrefix</xmlelement> element specifies the prefix to use when constructing the effective file names or resource IDs of the resources that are referenced from within the map branch that is implied by the ancestor <xmlelement>ditavalref</xmlelement> element.</ph>
<ph id="shortdesc-dvrResourceSuffix">The <xmlelement>dvrResourceSuffix</xmlelement> element specifies the prefix to use when constructing the effective file names or resource IDs of the resources that are referenced from within the map branch that is implied by the ancestor <xmlelement>ditavalref</xmlelement> element.</ph></lines>
    </section>
                <section id="section-3">
                        <title>Code blocks</title>
                        <codeblock id="concept-codeblock">&lt;topic id="intro-to-bird-calling"&gt;
 &lt;title&gt;Introduction to bird calling&lt;/title&gt;
 &lt;shortdesc&gt;If you want to attract more birds to your Acme Bird Feeder,
learn the art of bird calling. Bird calling is an efficient way
to alert more birds to the presence of your bird feeder.&lt;/shortdesc&gt;
 &lt;body&gt;
   &lt;p&gt;Bird calling requires learning:&lt;/p&gt;
   &lt;ul&gt;
    &lt;li&gt;Popular and classical bird songs&lt;/li&gt;
    &lt;li&gt;How to whistle like a bird&lt;/li&gt;
   &lt;/ul&gt;
 &lt;/body&gt;
&lt;/topic&gt;</codeblock>
                </section>
                <section id="section-4">
                        <title>Lists</title>
                        <ul id="cascading-attributes">
<li><xmlatt>rev</xmlatt></li>
<li><ph id="propsAndSpecializations"><xmlatt>props</xmlatt> and any
            attribute specialized from <xmlatt>props</xmlatt>, including
            those integrated by default in the OASIS-provided document-type
            shells: <xmlatt>audience</xmlatt>,
              <xmlatt>deliveryTarget</xmlatt>, <xmlatt>platform</xmlatt>,
              <xmlatt>product</xmlatt>,
          <xmlatt>otherprops</xmlatt></ph></li>
                                <li><xmlatt>linking</xmlatt>, <xmlatt>toc</xmlatt>,
            <xmlatt>search</xmlatt></li>
                                <li><xmlatt>format</xmlatt>, <xmlatt>scope</xmlatt>,
                                                <xmlatt>type</xmlatt></li>
                                <li><xmlatt>xml:lang</xmlatt>, <xmlatt>dir</xmlatt>,
                                                <xmlatt>translate</xmlatt></li>
                                <li><xmlatt>processing-role</xmlatt></li>
                                <li ><xmlatt>cascade</xmlatt></li>
        <li rev="2.0"><xmlatt>subjectrefs</xmlatt></li>
                        </ul>
                        <dl>
                                <dlentry  id="deliveryTarget">
                                        <dt><xmlatt>deliveryTarget</xmlatt></dt>
                                        <dd><ph id="deliveryTarget-simpleDefinition">Specifies the
              intended delivery target of the content, for example, <keyword>html</keyword>,
                <keyword>pdf</keyword>, or <keyword>epub</keyword>.</ph><p>The
                <xmlatt>deliveryTarget</xmlatt> attribute is specialized from the
                <xmlatt>props</xmlatt> attribute. It is defined in the deliveryTargetAttDomain,
              which is integrated into all OASIS-provided document-type shells. If this domain is
              not integrated into a given document-type shell, the <xmlatt>deliveryTarget</xmlatt>
              attribute will not be available.</p></dd>
                                </dlentry>
                        </dl>
                        <dl id="cascade-values">
                                <dlentry>
                                        <dt>merge</dt>
                                        <dd><ph rev="review-k">Indicates
              that the metadata attributes cascade, and that </ph>the
            values of the metadata attributes are additive. This is the
            processing default for the <xmlatt>cascade</xmlatt>
            attribute.</dd>
                                </dlentry>
                                <dlentry>
                                        <dt>nomerge</dt>
                                        <dd><ph rev="review-k">Indicates
              that the metadata attributes cascade, but that </ph>they are
            not additive for <xmlelement>topicref</xmlelement> elements
            that specify a different value for a specific metadata
            attribute. If the cascading value for an attribute is already
            merged based on multiple ancestor elements, that merged value
            continues to cascade until a new value is encountered<ph
              rev="review-k">. That is,</ph> setting
              <codeph>cascade="nomerge"</codeph> does not undo merging that
            took place on ancestor elements.</dd>
                                </dlentry>
                        </dl>
      <dl>
        <dlentry rev="2.0" id="aggregate-element-config-modules">
          <dt>Aggregation of constraint modules</dt>
          <dd>
            <p>The content model of an element can be modified by either of
              the following element-configuration modules:</p>
            <ul>
              <li>Constraint module</li>
              <li>Expansion module</li>
            </ul>
            <p><ph rev="review-p">For any document-type shell, the</ph>
              content model of an element can only be modified by a single
              element-type configuration module. If multiple constraints or
              extensions need to be applied to a single element, the
              element configurations must be combined into a single module
              that reflects all the constraints and expansions that were
              defined in the original separate modules.</p>
          </dd>
        </dlentry>
      </dl>
                </section>
<section id="definitions">
<title>Reused definitions</title>
<ul id="ul_mtt_k4g_thb">
<li><ph id="definitionChunkCombine">Instructs a processor to combine the
            referenced source documents for rendering purposes. <ph
              rev="review-h">This</ph> is intended for cases where a
            publishing process normally results in a single output artifact
            for each source XML document.</ph></li>
<li><ph id="definitionChunkSplit">Instructs a processor to split each topic
            from the referenced source document into its own document for
            rendering purposes. <ph rev="review-h">This</ph> is intended
            for cases where a publishing process normally results in a
            single output artifact for each source XML document, regardless
            of how many DITA topics exist within each source document.
          </ph></li>
</ul>
</section>

                <section id="section-5">
                        <title>Notes</title>
      <!--<note id="deprecated-print-attribute">Beginning with DITA 1.3, the <xmlatt>print</xmlatt> attribute is deprecated. It is replaced with a conditional processing attribute: <xmlatt>deliveryTarget</xmlatt>. See <xref keyref="attributes-universal/metadataatts/deliveryTarget"><xmlatt>deliveryTarget</xmlatt></xref> for more details.</note>-->
                        <note id="mapref-with-child-elements">If a <xmlelement>topicref</xmlelement>
                                element that references a map contains child
                                        <xmlelement>topicref</xmlelement> elements, the processing
                                behavior regarding the child <xmlelement>topicref</xmlelement>
                                elements is undefined.</note>
      <!--<note id="learning1learning2">DITA 1.3 defines two new domains for describing learning and training interactions: learningInteractionBase2Domain and learning2Domain. These two new domains mirror the DITA 1.2 learningInteractionBase and general learning domains, but the new versions provide support for multi-paragraph questions, answers, and feedback. The new domains are otherwise semantically identical to the original domains. For backwards compatibility, both interactions domains are supported in DITA 1.3. For new content, use the DITA 1.3 learning2Domain elements.</note>-->
                </section>

                <section id="section-6">
                        <title>Paragraphs</title>
                        <p id="attribute-implementation-tokens"
        >Implementers <term outputclass="RFC-2119">MAY</term> define their
        own custom, implementation-specific tokens for the
          <xmlatt>merge</xmlatt> attribute. To avoid name conflicts between
        implementations or with future additions to the standard,
        implementation-specific tokens <term outputclass="RFC-2119"
          >SHOULD</term> consist of a prefix that gives the name or an
        abbreviation for the implementation followed by a colon followed by
        the token or method name. For example, a processor might define the
        token "appToken:audience" in order to specify cascading and merging
        behaviors for <b>only</b> the <xmlatt>audience</xmlatt>
        attribute.</p>
      <!--<p id="module-version-xpl">The identifiers listed below are declared by the OASIS DITA Technical Committee for the modules that are shipped with DITA 1.3. Values that use a version number of 1.3 refer specifically to the modules that are delivered with the DITA 1.3 specification. Values that use a version number of 1.x refer to the modules in the latest approved DITA 1.x specification. Values without a version number refer to the modules in the latest approved DITA specification, regardless of version.</p>-->
                        <p id="keys-attribute-syntax">The <xmlatt>keys</xmlatt> attribute uses the
                                following syntax:<ul id="ul_yxs_dr5_yl">
                                        <li>The value of the <xmlatt>keys</xmlatt> attribute is one
                                                or more space-separated key names.</li>
                                        <li> Key names consist of characters that are legal in a
                                                URI. The case of key names is significant.</li>
                                        <li>The following characters are prohibited in key names:
                                                "{", "}", "[", "]", "/", "#", "?", and whitespace
                                                characters.</li>
                                </ul></p>
                        <p id="release-domain-best-practices">The recommended best practice is to
        use date strings that conform to the ISO 8601 standard, unless a <ph 
          >UNIX-style</ph> machine time stamp is used. The string might contain a date and time (for
        example, <codeph>2017-04-05T12:30-02:00</codeph>) or just a date (for example,
          <codeph>2019-03-04</codeph>).</p>
                        <p id="pgwide-explain">For
          <xmlelement>table</xmlelement>, in place of the
          <xmlatt>expanse</xmlatt> attribute that is used by other DITA
        elements, the <xmlatt>pgwide</xmlatt> attribute is used in order to
        conform to the OASIS Exchange Table
        Model.<!-- The <xmlatt>pgwide</xmlatt> attribute has a similar semantic (<keyword>1</keyword>=page width; <keyword>0</keyword>=resize to galley or column). --></p>
      <div id="sort-as-construction">
        <p id="sort-as-1">When a <xmlelement>sort-as</xmlelement> element is specified, processors
          that sort the containing element <term outputclass="RFC-2119">MUST</term> construct the
          effective sort phrase by prepending the content of the <xmlelement>sort-as</xmlelement>
          element to the base sort phrase. This ensures that two items with the same
            <xmlelement>sort-as</xmlelement> element but different base sort phrases will sort in
          the appropriate order.</p>
        <p otherprops="examples" id="sort-as-2">For example, if a processor uses the content of the
            <xmlelement>title</xmlelement> element as the base sort phrase, and the title of a topic
          is "24 Hour Support Hotline" and the value of the <xmlelement>sort-as</xmlelement> element
          is "twenty-four hour", then the effective sort phrase would be "twenty-four hour24 Hour
          Support Hotline".</p>
      </div>
      <p id="rng-attribute-domain-name">The name of an attribute domain is the name of the attribute
        plus <keyword>Att</keyword>. For example, for the attribute named
          <xmlatt>deliveryTarget</xmlatt>, the attribute-domain name is "deliveryTargetAtt". The
        attribute-domain name is used to construct pattern names for the domain. </p>
      <p id="dtd-attribute-domain-name">The name of an attribute domain is the name of the attribute
        plus <keyword>Att</keyword>. For example, for the attribute named
          <xmlatt>deliveryTarget</xmlatt>, the attribute-domain name is "deliveryTargetAtt". The
        attribute-domain name is used to construct entity names for the domain. </p>
                </section>

                <section id="section-7">
                        <title>Phrases</title>
                        <lines>
 <ph id="does-it-cascade">Does it cascade to child <xmlelement>topicref</xmlelement> elements?</ph>
<ph id="highlight-caution">This element is part of the highlighting domain. Use this element only when a more semantically appropriate element is not available.</ph>
<ph id="xml-mention-domain">This element is part of the XML mention domain.</ph>
<ph id="groupdefn">The attribute can also include groups of values specified using the same syntax as generalized attributes within <xmlatt>props</xmlatt>; see <xref href="../archSpec/base/generalization-attributes.dita"/> for details on grouping syntax.</ph>
<ph id="dateformat">The date is specified using the ISO 8601 format: <varname>YYYY</varname>-<varname>MM</varname>-<varname>DD</varname>, where <varname>YYYY</varname> is the year, <varname>MM</varname> is the month (01 to 12), and <varname>DD</varname> is the day (01-31).</ph></lines>
                </section>
                <section id="section-9"><title>Reused error conditions</title><ph id="index-sort-as">When located
                                within the <xmlelement>indexterm</xmlelement> element, the
                                        <xmlelement>sort-as</xmlelement> element is equivalent to
                                        <xmlelement>index-sort-as</xmlelement>. It is an error for
                                an <xmlelement>indexterm</xmlelement> element to directly contain
                                both <xmlelement>sort-as</xmlelement> and
                                        <xmlelement>index-sort-as</xmlelement>
                        elements.</ph></section>
    <section id="section-10">
      <title>Constraints material</title>
      <ul id="dtd-domains-contribution">
        <li id="inheritance-hierarchy-li"><varname>inheritance-hierarchy</varname> is the
          specialization hierarchy, for example, <codeph>topic task</codeph>.</li>
        <li id="qualifier-li"><varname>qualifier</varname> is a string that is specific to the
          constraints module and characterizes it, for example, "strict" or "requiredTitle" or
          "myCompany-".</li>
        <li id="Tagname-li"><varname>Target</varname> is the target of the
          constraint with an initial capital, for example, "Topic" or
          "HighlightDomain".</li>
        <li id="literal-c-li">The literal "-c" indicates that the name is the name of a
          constraint.</li>
      </ul>
      <ul id="dtd-domains-contribution-domain-constraint">
        <li><varname>inheritance-hierarchy</varname> is the specialization hierarchy, for example,
            <codeph>topic hi-d</codeph>.</li>
        <li><varname>qualifier</varname> is a string that is specific to the constraints module and
          characterizes it, for example, "noSyntaxDiagram" or "myCompany-".</li>
        <li><varname>domain</varname> is the name of the domain to which the constraints apply, for
          example, "Highlighting" or "Programming".</li>
        <li conref="#reuse_file/literal-c-li"/>
      </ul>
      <ul id="dtd-domains-constraint">
        <li><varname>qualifier</varname> is a string that is specific to the constraints module and
          characterizes it, for example, "noSyntaxDiagram" or "myCompany-".</li>
        <li><ph id="domain-variable-ph"><varname>domain</varname> is the name of the domain to which
            the constraints apply, for example, "Highlighting" or "Programming".</ph></li>
      </ul>
    </section>
    <section id="section-11">
      <title>File naming conventions</title>
      <p  id="see-file-naming-conventions">See <xref
          href="../non-normative/file-naming-conventions.dita"/> for information about best
        practices for file naming.</p>
      <p  id="indicating-strong-constraint">Optionally, a domains contribution
        can indicate a strong constraint by preceding the domains contribution with the letter "s".
        For example, <codeph>"s(topic task strictTaskbody-c)"</codeph> indicates a strong
        constraint.</p>
    </section>
    <section id="section_nw3_3pr_wsb">
      <title>DITAVAL reuse material</title>
      <div id="processing-outputclass">
        <p>The following list outlines how processors apply
            <xmlatt>outputclass</xmlatt> flags:</p>
        <ul>
          <li>If one or more DITAVAL properties apply
              <xmlatt>outputclass</xmlatt> flags to the same element, and
            the element already specifies one or more values for the
              <xmlatt>outputclass</xmlatt> attribute, processors treat the
            element as if <ph rev="review-m">the tokens for the
                <xmlatt>outputclass</xmlatt> attribute that were provided
              in the DITAVAL document</ph> are specified first.</li>
          <li>If two or more DITAVAL properties apply
              <xmlatt>outputclass</xmlatt> flags to the same element,
            processors treat the element as if each value was specified for
            the <xmlatt>outputclass</xmlatt> attribute. The order of the
              <ph rev="review-m"> tokens for the
                <xmlatt>outputclass</xmlatt> attribute that were provided
              in the DITAVAL document</ph> is undefined.</li>
        </ul>
      </div>
    </section>
    <section id="processing-expectations-link-cascade" rev="review-h">
      <title>Processing expectations</title>
      <p>Attributes that cascade between topic references in a map<ph rev="review-j">, such as the
            <xmlatt>scope</xmlatt> and <xmlatt>format</xmlatt> attributes,</ph> also cascade from
        this element to contained links.</p>
    </section>
        </conbody>
</concept>