source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/flagging-migration.dita@ 99040

<?xml version="1.0" encoding="UTF-8"?>
<!--Arbortext, Inc., 1988-2011, v.4002-->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
 "reference.dtd">
<reference id="flagging-migration" rev="1.7" xml:lang="en-us">
<title>XHTML migration for flagging updates in DITA-OT 1.7</title>
<shortdesc>This topic is primarily of interest to developers with
XHTML transform overrides written prior to DITA-OT 1.7. Due to significant
changes in the flagging process with the 1.7 release, some changes
may be needed to make overrides work properly with DITAVAL based flagging.
The new design is significantly simpler than the old design; in many
cases, migration will consist of deleting old code that is no longer
needed.</shortdesc>
<refbody>
<section><title>Which XHTML overrides need to migrate?</title><p>If
your override does not contain any code related to DITAVAL flagging,
then there is nothing to migrate.</p><p>If your builds do not make
use of DITAVAL based flagging, but calls the deprecated flagging templates,
then you should override but there is little urgency. You will not
see any difference in the output, but those templates will be removed
in a future release.</p><p>If you do make use of DITAVAL based flagging,
try using your override with 1.7. Check the elements you override:<ol>
<li>In some cases flags may be doubled. This will be the case if you
call routines such as <codeph>"start-flagit"</codeph>.</li>
<li>In some cases flags may be removed. This will be the case if you
call shortcut routines such as <codeph>"revtext"</codeph> or <codeph>"revblock"</codeph>.</li>
<li>In other cases, flags may still appear properly, in which case
migration is less urgent</li>
</ol></p><p>For any migration that needs migration, please see the
instructions that follow.</p></section>
<section><title>Deprecated templates in DITA-OT 1.7</title><p>All
of the old DITAVAL based templates are deprecated in DITA-OT 1.7.
If your overrides include any of the following templates, they should
be migrated for the new release; in many cases the templates below
will not have any effect on your output, but all instances should
be migrated.</p><ul>
<li>The <codeph>"gen-style"</codeph> template used to add CSS styling</li>
<li>The <codeph>"start-flagit"</codeph> and <codeph>"end-flagit"</codeph> templates
used to generate image flags based on property attributes like @audience</li>
<li>The <codeph>"start-revflag"</codeph> and <codeph>"end-revflag"</codeph> templates,
used to generate images for active revisions</li>
<li>Shortcut templates that group these templates into a single call,
such as:<ul>
<li><codeph>"start-flags-and-rev"</codeph> and <codeph>"end-flags-and-rev"</codeph>,
used to combine flags and revisions into one call</li>
<li><codeph>"revblock"</codeph> and <codeph>"revtext"</codeph>, both
used to output start revisions, element content, and end revisions</li>
<li>The modes <codeph>"outputContentsWithFlags"</codeph> and <codeph>"outputContentsWithFlagsAndStyle"</codeph>,
both used to combine processing for property/revision flags with content
processing</li>
</ul></li>
<li>All other templates that make use of the <codeph>$flagrules</codeph> variable,
which is no longer used in any of the DITA-OT 1.7 code</li>
<li>All templates within <filepath>flag.xsl</filepath> that were called
from the templates listed above</li>
<li>Element processing handled with mode="elementname-fmt", such as <codeph>mode="ul-fmt"</codeph> for
processing unordered lists and <codeph>mode="section-fmt"</codeph> for
sections.</li>
</ul></section>
<section><title>What replaces the templates?</title><p>The new flagging
design described in the preprocess design section now adds literal
copies of relevant DITAVAL elements, along with CSS based flagging
information, into the relevant section of the topic. This allows most
flags to be processed in document order; in addition, there is never
a need to read the DITAVAL, interpret CSS, or evaluate flagging logic.
The <filepath>htmlflag.xsl</filepath> file contains a few rules to
match and process the start/end flags; in most cases, all code to
explicitly process flags can be deleted.</p><p>For example, the common
logic for most element rules before DITA-OT 1.7 could be boiled down
to the following:<lines>Match element
    Create <codeph>"flagrules"</codeph> variable by reading DITAVAL for active flags
    Output start tag such as <codeph>&lt;div></codeph> or <codeph>&lt;span></codeph>
        Call <codeph>"commonattributes"</codeph> and ID processing
        Call <codeph>"gen-style"</codeph> with <codeph>$flagrules</codeph>, to create DITAVAL based CSS
        Call <codeph>"start-flagit"</codeph> with <codeph>$flagrules</codeph>, to create start flag images
        Call <codeph>"start-revflag"</codeph> with <codeph>$flagrules</codeph>, to create start revision images
        Output contents
        Call <codeph>"end-revflag"</codeph> with <codeph>$flagrules</codeph>, to create end revision images
        Call <codeph>"end-flagit"</codeph> with <codeph>$flagrules</codeph>, to create end flag images
    Output end tag such as <codeph>&lt;/div></codeph> or <codeph>&lt;/span></codeph></lines></p><p>In
DITA-OT 1.7, style and images are typically handled with XSLT fallthrough
processing. This removes virtually all special flag coding from element
rules, because flags are already part of the document and processed
in document order. The sample above is reduced to:<lines>Match element
   Output start tag such as <codeph>&lt;div></codeph> or <codeph>&lt;span></codeph>
      Call <codeph>"commonattributes"</codeph> and ID processing
      Output contents
   Output end tag such as <codeph>&lt;/div></codeph> or <codeph>&lt;/span></codeph></lines></p></section>
<section><title>Migrating <codeph>"gen-style"</codeph> named template</title><p>Calls
to the <codeph>"gen-style"</codeph> template should be deleted. There
is no need to replace this call for most elements.</p><p>The <codeph>"gen-style"</codeph> template
was designed to read a DITAVAL file, find active style-based flagging
(such as colored or bold text), and add it to the generated @style
attribute in HTML.</p><p>With DITA-OT 1.7, the style is calculated
in the pre-process flagging module. The result is created as @outputclass
on a <codeph>&lt;ditaval-startprop></codeph> sub-element. The <codeph>"commonattributes"</codeph> template
now includes a line to process that value; the result is that for
every element that calls <codeph>"commonattributes"</codeph>, DITAVAL
style will be processed when needed. Because virtually every element
includes a call to this common template, there is little chance that
your override needs to explicitly process the style. The new line
in <codeph>"commonattributes"</codeph> that handles the style is: <codeblock>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]/@outputclass" mode="add-ditaval-style"/></codeblock></p></section>
<section><title>Migrating <codeph>"start-flagit"</codeph>, <codeph>"start-revflag"</codeph>, <codeph>"end-flagit"</codeph>,
and <codeph>"end-flagit"</codeph> named templates</title><p>Calls
to these templates fall into two general groups.</p><p>If the flow
of your element rule is to create a start tag like <codeph>&lt;div></codeph>, <codeph>"start-flagit"</codeph>/<codeph>"start-revflag"</codeph>,
process contents, <codeph>"end-revflag"</codeph>/<codeph>"end-flagit"</codeph>,
end tag - you just need to delete the calls to these templates. Flags
will be generated simply by processing the element contents in document
order.</p><p>If the flow of your element rule processes flags outside
of the normal document-order. There are generally two reasons this
is done. The first case is for elements like <codeph>&lt;ol></codeph>,
where flags must appear before the <codeph>&lt;ol></codeph> in order
to create valid XHTML. The second is for elements like <codeph>&lt;section></codeph>,
where start flags are created, followed by the title or some generated
text, element contents, and finally end flags. In either of these
cases, support for processing flags in document order is disabled,
so they must be explicitly processed out-of-line. This is done with
the following two lines (one for start flag/revision, one for end
flag/revision):<codeblock>Create starting flag and revision images:
&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]" mode="out-of-line"/>

Create ending flag and revision images:
&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]" mode="out-of-line"/></codeblock></p><p>For
example, the following lines are used in DITA-OT 1.7 to process the <codeph>&lt;ul></codeph> element
(replacing the 29 lines used in DITA-OT 1.6):<codeblock>&lt;xsl:template match="*[contains(@class,' topic/ul ')]">
  <b>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-startprop ')]" mode="out-of-line"/></b>
  &lt;xsl:call-template name="setaname"/>
  &lt;ul>
    &lt;xsl:call-template name="commonattributes"/>
    &lt;xsl:apply-templates select="@compact"/>
    &lt;xsl:call-template name="setid"/>
    &lt;xsl:apply-templates/>
  &lt;/ul>
  <b>&lt;xsl:apply-templates select="*[contains(@class,' ditaot-d/ditaval-endprop ')]" mode="out-of-line"/></b>
  &lt;xsl:value-of select="$newline"/>
&lt;/xsl:template></codeblock></p></section>
<section><title>Migrating <codeph>"start-flags-and-rev"</codeph> and <codeph>"end-flags-and-rev"</codeph></title><ul>
<li><codeph>"start-flags-and-rev"</codeph> is equivalent to calling <codeph>"start-flagit"</codeph> followed
by <codeph>"start-revflag"</codeph>; it should be migrated as in the
previous section.</li>
<li><codeph>"end-flags-and-rev"</codeph> is equivalent to calling <codeph>"end-revflag"</codeph> followed
by <codeph>"end-flagit"</codeph>; it should be migrated as in the
previous section.</li>
</ul></section>
<section><title>Migrating <codeph>"revblock"</codeph> and <codeph>"revtext"</codeph></title><p>Calls
to these two templates can be replaced with a simple call to <codeph>&lt;xsl:apply-templates/></codeph>.</p></section>
<section><title>Migrating modes <codeph>"outputContentsWithFlags"</codeph> and <codeph>"outputContentsWithFlagsAndStyle"</codeph></title><p>Processing
an element with either of these modes can be replaced with a simple
call to <codeph>&lt;xsl:apply-templates/></codeph>.</p></section>
<section><title>Migrating <codeph>mode="elementname-fmt"</codeph></title><p>Prior
to DITA-OT 1.7, many elements were processed with the following logic:<pre>Match element
    Set variable to determine if revisions are active and $DRAFT is on
    If active
        create division with rev style
            process element with mode="elementname-fmt"
        end division
    Else
        process element with mode="elementname-fmt"

Match element with mode="elementname-fmt"
    Process as needed</pre></p><p>Beginning with DITA-OT 1.7, styling
from revisions is handled automatically with the <codeph>"commonattributes"</codeph> template.
This means there is no need for the extra testing, or the indirection
to <codeph>mode="elementname-fmt"</codeph>. These templates are deprecated,
and element processing will move into the main element rule. Overrides
that include this indirection may remove it; overrides should also
be sure to match the default rule, rather than matching with <codeph>mode="elementname-fmt"</codeph>.</p></section>
</refbody>
</reference>