source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/preprocess-content-changes.dita@ 99040

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
"reference.dtd">
<reference id="preprocess-content-changes" rev="1.8" xml:lang="en-us">
  <title>Content changes that occur during pre-processing</title>
  <shortdesc>Pre-processing introduces changes to the DITA content that you might want to be aware
    of if you work with the temporary files. While some steps, such as conref resolution, change the
    DITA content in a way that is expected and mandated by the DITA specification, other steps
    result in temporary output that does not comply with the DITA standard. In addition, if you are
    using a restrictive specialization, the pre-processing steps might introduce content that is not
    permitted by the content model of the specialization.</shortdesc>
  <prolog>
    <author type="creator">Robert D. Anderson</author>
    <author type="contributor">Kristen James Eberlein</author>
    <copyright>
      <copyryear year="2013"/>
      <copyrholder>DITA Open Toolkit </copyrholder>
    </copyright>
    <critdates>
      <created date="2013-03-29"/>
    </critdates>
  </prolog>
  <refbody>
    <section><title>Changes that do not comply with the DITA standard</title><p>The DITA-OT makes certain changes to documents during the pre-processing operation, in order to
        simplify or optimize later stages in the processing chain. These changes result in temporary
        files that do not comply with the DITA standard.<draft-comment author="Kristen Eberlein"
          time="29 March 2013">Robert, I don't think that the first two items are correctly phrased.
          I couldn't manage to generate either the image or mapclass attributes in my intermediate
          files ...</draft-comment><dl>
          <dlentry>
            <dt>Image attributes</dt>
            <dd>If the document contains images, the DITA-OT adds @dita-ot:image-width and
              @dita-ot:image-height attributes to the &lt;image> elements. These attributes enable
              scaling when the images are finally rendered.</dd>
          </dlentry>
          <dlentry>
            <dt>@mapclass attribute on generated links</dt>
            <dd>When links are generated based on information in the DITA map, a @mapclass attribute
              is added to the &lt;link> element that indicates the class of the &lt;topicref>
              element used to create the map. This attribute can be used to sort links or filter how
              links are displayed in output.</dd>
          </dlentry>
          <dlentry>
            <dt>Flagging</dt>
            <dd>The flagging stage of the pre-processing operation creates pseudo-specializations of
              the &lt;foreign> element which contain flagging information. Flagging some elements,
              such as &lt;topic> and &lt;row>, results in markup where the pseudo-specialization of
              the &lt;foreign> element is the first and last child of the element. </dd>
          </dlentry>
        </dl></p></section>
    <section><title>Changes that might not comply with restrictive specializations</title><p>Some changes made during the pre-processing operation might not comply with restrictive
        specialization. Most of these changes are listed here, athough the list is not exhaustive.
        If you develop an output transformation for a restrictive specialization, you should be
        aware of these changes. If necessary, you can customize the pre-processing operation  to
        avoid these changes.<dl>
          <dlentry>
            <dt>Related links</dt>
            <dd>The maplink step of the pre-processing operation generates contextual links based on
              the maps, for example, next and previous links; this step uses the &lt;related-links>
              element to contain the contextual links. This can cause unexpected output if a
              specialized document type has removed the &lt;related-links> element.</dd>
          </dlentry>
          <dlentry>
            <dt>Cascade of map  metadata</dt>
            <dd>When metadata is specified in a map, it generally cascades to nested &lt;topicref>
              elements and the referenced topics. If the map contains specialized metadata elements
              or attributes, the metadata might cascade to &lt;topicref> elements or topic
              &lt;prolog> elements that are not intended to have the metadata. If a topic document
              type has been specialized to disallow metadata, metadata specified in the map might
              nonetheless cascade into the topic &lt;prolog> element.</dd>
          </dlentry>
          <dlentry>
            <dt>Title text in links</dt>
            <dd> By default, links or cross references without link text are updated to include link
              text. The link text is generally generated by using the title of the referenced topic.
              This can cause unexpected output if cross references or links have been specialized
              and the specialized content model does not allow text.</dd>
          </dlentry>
          <dlentry>
            <dt>@xtrf  and  @xtrc elements</dt>
            <dd>The pre-processing operation adds these two attributes to every element, in order to
              provide trace-back information in case of errors. These attributes are added even for
              specializations that forgot to define these attributes.</dd>
          </dlentry>
        </dl></p></section>
    <section><title>Changes or files that are not intended to comply with existing document types</title><p>Some processes in the toolkit are not designed to produce documents that comply fully with a DITA
        DTD or XSD.<dl>
          <dlentry>
            <dt>Topic merge</dt>
            <dd>The topicmerge process is used by the PDF, ODT, and RTF transformations to produce a
              single document that contains all of the content that is referenced by the master map.
              This file is not DITA and is specific to the DITA-OT. Its purpose is to simplify
              processing for output transformations that result in a single document.</dd>
          </dlentry>
          <dlentry>
            <dt>Chunking</dt>
            <dd>When the @chunk attribute is used in a map, DITA documents might be split or merged
              in a way that does not comply with any existing document type. For example, merging
              documents might result in a topic that nests concept, task, and specialized
              troubleshooting topics, even if no existing DTD or Schema permits that combination in
              a document.</dd>
          </dlentry>
        </dl>
      </p></section>
  </refbody>
</reference>