To change the way the main processor, topic2html.xsl, produces XHTML output, you can work with the following variables and parameters.
If you need to make code changes to topic2html.xsl to change a variable value, the preferred mechanism is to create an override transform and place your changed code there. Editing any of the DITA distribution files directly is not recommended in case of package updates that might wipe out your changes! The file dita2html_shell.xsl in the xsl directory is an example of an override transform: copy it to a new filename and add your XSLT changes within the copy. Making edit changes to XSLT transforms is outside the scope of this document; please refer to a good XSLT reference for guidance!
Note: You are responsible for any changes you make with DITA transforms! If you need help, the DITA forum on developerWorks may be a useful resource.
To change the values of the following global variable declarations to meet your publication requirements, copy the appropriate XSL directive into an override stylesheet which imports topic2html.xsl and make your editing changes there.
Variable name | Explanation | Default Value |
---|---|---|
afill | Filler for A-name anchors (link-to points that have no data content in and of themselves; some browsers fail to link if a named anchor has no text) | null string (could be a space character, ,  , etc.) |
copyright | The copyright string that will be placed as a comment within your HTML output. Change to match the ownership of your XML content! | "Copyright 2003" |
For example, copy the copyright variable declaration into your override stylesheet and change the content to represent the actual copyright owner of your content (this string will be copied into the result HTML document as a comment):
<xsl:variable name="copyright">Copyright MyCompany Ltd., 2002</xsl:variable>
These default values can be changed at run time by using the parameter-passing syntax of your XSLT processor (if it supports command-line parameters). If your processor does not support parameter-passing on the command line, copy the XSL directives you wish to change into an override XSLT stylesheet, change the values as needed, and import topic2html.xsl at the top of this new stylesheet. dita2html_shell.xsl is an example of an override stylesheet that you can copy and modify as needed.
Parameter name | Explanation | Default value |
---|---|---|
default-css | Default CSS filename parameter, usually the name of your site's overall stylesheet. | "common.css" |
CSS | User's CSS filename parameter. This can be the name of a stylesheet used by one or more topics within an overall group. This stylesheet can use the CSS cascade effect to modify existing properties or it can override or define new properties. |
(null) |
CSSPATH | Default CSS path parameter. This specifies a path for the cascading style sheet (CSS). This allows you to place the CSS in one place and have several different topics point to it. If no CSSPATH is specified, the CSS is assumed to be in the same directory as the XHTML. |
(null) |
IP | Default image path parameter (where the posted images will be relative to the posted HTML file--can also be an absolute URL path; the processor will append the image filename onto whatever value is provided here.) | (null) |
ARTLBL | Default "output artwork filenames" processing parameter; "no"and "yes"are valid values; non-"yes" is ignored. | "no" |
DRAFT | Default "hide draft & cleanup content" processing parameter ("no"= hide them); "no" and "yes" are valid values; non-"yes" is ignored. | "no" |
INDEXSHOW | Default "hide index entries" processing parameter ("no" = hide them); "no" and "yes" are valid values; non-"yes" is ignored. | "no" |
SRCEXT | Default "source extension" processing parameter; "xml" and "dita" are valid values. | "xml" |
OUTEXT | Default "output extension" processing parameter; "htm" and "html" are valid values. | "html" |
WORKDIR | The working directory, relative to the stylesheet, that contains the document being transformed. Needed as a directory prefix for the @conref and @href "document()" function calls. | "./" |
FILENAME | The file name (file name and extension only - no path) of the document
being transformed. Needed to help form debugging messages. Note: This value is not inherent to the XSLT processor; typically, your calling exec will pass the input filename to the processor's command line as a parameter. Any resulting debugging messages will echo the filename. |
"myfile.xml" |
DBG | Debug mode - enables XSL debugging xsl-messages. Needed to help form debugging messages. "no" and "yes" are valid values; non-"yes" is ignored. | "no" |
Lang | Default language parameter for generated text (for example, "Note: "). | "en-us" |
For example, the following sample invocation shows how to turn on draft mode using the Saxon XSLT processor:
c:pkg\dita12\doc>saxon -o abc.htm dita-tweaks.xml ..\xsl\topic2html.xsl DRAFT=yes
The effect of this parameter will be to show the content of all <draft-comment> and <required-cleanup> elements with highly visible styling for use by reviewers.
Note: To invoke a process using parameters, please check the documentation for your XSLT processor. Most current XSLT 1.0 processors support a non-standard command line interface for parameters.
Note: Parametric tweaks cannot be applied from internal stylesheet links (that is, the <?xml-stylesheet ...?> processing instruction) as such associations do not provide a way to pass parameters, even if a browser-specific renderer is capable of using such data. To cause a browser-based view to show something ordinarily affected by a command-line parameter, such as the DRAFT="yes" effect, embed the alternative value directly in the override stylesheet that is named in the stylesheet processing instruction:
<xsl:param name="DRAFT" select="'yes'"/>
The following variables regulate some output behaviors of the topic2html.xsl stylesheet. These behaviors are typically considered "business rules" in the sense that they enforce strict format guidelines preferred by a content owner. By overriding the values, you can change the output in a controlled way for all your processing.
Variable name | Explanation | Default Value |
---|---|---|
fmt-fig-lbl-loc | Placement of a figure's title: "over" the figure, or "under" the figure. | "over" |
fmt-tbl-lbl-loc | Placement of a table's title: "over" the table, or "under" the table. | "over" |
link-top-section | Placement of a "Return to Top" link at the end of each section in a topic. "yes", "no" (or any not "yes"). | "no" |
do-place-ing | Placement of an informational navigation graphic (ing) relative to particular features on a page. "yes", "no" (or any not "yes"). Not fully functional. | "no" |
For example, copy the link-top-section variable declaration into your override stylesheet and change the content from "no" to "yes" to cause a "Return to Top" link to be inserted following each section within a topic:
<!-- turn on return links from end of sections --> <xsl:variable name="link-top-section">yes</xsl:variable>
The topic2html.xsl stylesheet provides code stubs that extend the appearance of your HTML result document. If you copy these stubs into your override stylesheet and provide your own code within them, the result content will be pasted into appropriate parts of the overall HTML page.
Regions that can be modified by these stubs include header, footer, topic-top blurbs (a common location for mini-contents boxes), self-contained scripts (such as JavaScript used commonly for DHTML support), self-contained styles, flagging based on property value matches, panel titles and prefixes for panel titles (to auto-generate explicit bookmarks for your users). See the section of topic2html.xsl called "start of override stubs" for the examples of mostly-empty stubs that you can modify.
For example, copy the following template rule into an override file, such as a copy of dita2html_shell.xsl, to cause a "mini-table of contents" to be generated at the top of a topic that directly nests child topics:
<!-- override for main stub --> <xsl:template name="gen-user-sidetoc"> <!-- if there are nested topics... --> <xsl:if test="descendant::*[contains(@class,' topic/topic ')]"> <p> <table width="150" align="right" border="1" frame="box" rules="none"> <tr><td height="5" bgcolor="#0033CC" align="center"> <b><font color="#FFFFFF">Contents:</font></b></td> </tr> <xsl:for-each select="descendant::*[contains(@class,' topic/topic ')]"> <xsl:variable name="ttext"><xsl:value-of select="*[contains(@class,' topic/title ')]"/></xsl:variable> <tr><td class="toc">- <a href="#{generate-id()}"><xsl:value-of select="$ttext"/></a> <!--recursive call for subtopics here"/--> </td></tr> </xsl:for-each> </table> </p> </xsl:if> </xsl:template>
Remember: Do your modifications on copies of stylesheets so that you can fall back on the original!
Testing some tweaks
This section makes use of several tweak-controllable features. It contains a draft comment, a required cleanup container, a figure whose title can be shifted over or under the figure upon output, and a section title that can be augmented with a graphical "information navigation icon" or ing (see do-place-ing under Behaviors).
Note: This document will appear differently depending on which stylesheet you use to view it. If you view or process it with a standard shell (dita2html_shell.xsl or dita2fo_shell.xsl), the special features will not be turned on. But if you process it into HTML (or view it directly in IE6) using the myoverrides.xsl demo stylesheet the special features WILL be enabled, and cause differences in the rendering of the output.
Tip: If you code your note type as "tip" and turn on the do-place-ing behavior, as with this note, the output should include a graphical icon alongside the text label.
^^ This is a footnote with a special callout character.