Appendix B. Limitations and implementation specificities

Conversion to XHTML and XSL-FO

  • The following elements are ignored:
  • The <titlealts>/<navtitle> element of topic is ignored.
  • Layout of <simpletable> elements:
    • Attribute @frame is ignored.
    • Conversion to XHTML:
      • Attribute @expanse is partially supported. Its value is considered to always be 100%.
    • Conversion to XSL-FO:
      • Attribute @expanse is ignored. The width of a <simpletable> is always 100% and thus, you cannot center a <simpletable> using the center parameter.
  • Layout of (CALS) <table> element:
    • Attributes <table>/@orient and <entry>/@rotate are not supported.
    • Conversion to XHTML:
      • Attribute @pgwide is partially supported. Its value is considered to always be 100%.
      • Something like colwidth="2*+3pt" is treated as if it were colwidth="2*". Moreover, because no Web browser seems to support relative lengths, a relative length is approximated to a percentage.
    • Conversion to XSL-FO:
      • Attribute @pgwide is ignored. The width of a <table> is always 100% and thus, you cannot center a <table> using the center parameter.
  • The qualified ID of a descendant element of a topic is transformed as follows: topicID/descendantID becomes topicID__descendantID in the generated content. (The separator string being used comprises two underscore characters.)
    Example: let's suppose a topic having "parameters" as its @id attribute, containing a table having "default_values" as its @id attribute, has been converted to HTML. The generated HTML file which contains the topic is called userguide.html.
    • URL "userguide.html#parameters" allows to address the topic.
    • URL "userguide.html#parameters__default_values" allows to address the table.

Booklists

  • Contents corresponding to the following empty <bookmap> elements: <toc>, <tablelist>, <figurelist>, <indexlist> can be automatically generated by ditac.
  • Ditac supports <examplelist> and <equationlist> in addition to <toc>, <tablelist>, <figurelist>, <indexlist>.
  • Contents corresponding to the following empty <bookmap> elements: <trademarklist>, <abbrevlist>, <bibliolist>, <glossarylist> cannot be automatically generated by ditac.
  • About the automatically generated <indexlist>:
    • Specifying an <indexterm> element in the <topicmeta>/<keywords> element of a <topicref> element is equivalent to specifying it in the <prolog>/<metadata>/<keywords> element of the corresponding topic. Any other <indexterm> element found in a map is ignored.
    • In a topic, the implicit end of an index range is always after the last child of the topic, not including nested topics.
    • Overlapping index ranges are not supported.
    • The markup possibly contained in an <indexterm> (<option>, <parmname>, <apiname>, etc) is ignored.
    • Because we consider this feature to be truly useful, we'll generate page references and ``see also'' redirections even for non-leaf index terms. No warnings will be reported in this case. If you don't like this specificity, simply do not author such <indexterm> elements.
    • Unless specified using the -lang command-line option, the language of the document is taken from the @xml:lang attribute of the root element of the topic map. If there is no such attribute, the language defaults to "en". Knowing the language of the document is required to be able to generate localized text (e.g. "Kapitel") and to sort and group the index entries.

Keyref processing

  • Matching element content taken from a key definition is limited to the following cases:
    • A <link> element gets its <linktext> child from key_definition/topicmeta/linktext and its <desc> child from key_definition/topicmeta/shortdesc.
    • An <xref> element gets its contents from key_definition/topicmeta/linktext.
    • Elements <ph>, <cite>, <keyword>, <dt> and <term> all get their content from key_definition/topicmeta/keywords/keyword, if any. Otherwise the contents of key_definition/topicmeta/linktext is used as a fallback.
  • Key-based, cross-deliverable addressing Opens in new window is not implemented.
  • Topics which are not directly or indirectly referenced by the root map are automatically added to the root key scope. Such topics typically contain common content which is included by other topics using @conref.
    If you don't want this to happen, please explicitly reference such common content topics in your maps and mark these references as being resource-only. Example:
    <topigroup keyscope="MyKeycope">
      <topicref href="commonContent.dita" processing-role="resource-only"/>

Transclusion

  • During a conref transclusion, ditac does not check the compatibility of the domains of the referencing document with the domains of the referenced document. This can be changed by defining system property DITAC_CHECK_DOMAINS (that is, adding -DDITAC_CHECK_DOMAINS=1 to the bin/ditac shell script or to bin/ditac.bat). However, the verifications performed by ditac are almost certainly not conforming as we have not really understood the spec.
  • Transclusion does not implement automatic generalization. For example, transcluding <li conref="foo.dita#foo/item3"/> will report a fatal error if "foo/item3" is a <step> element.
    A <step> element is a specialization of a <li> element. Some DITA processors are capable of automatically converting a <step> element to an <li> element. This is not the case of ditac.

Cascading of attributes and metadata

  • Filtering and flagging may be performed using any attribute. However only the following attributes: <audience>, <platform>, <product>, <otherprops>, <props>, specializations of attributes <props> and <rev> properly cascade with a map, within the <related-links> element of a topic and from a <topicref> element to the referenced <topic> element.
  • Both attribute (e.g. @audience) and element (e.g. <audience>) metadata are copied from a <topicref> element to the referenced <topic> element.
  • Unless topicref/topicmeta/@lockmeta=no, topicref/topicmeta/searchtitle supplements or overrides topic/titlealts/searchtitle.
  • In the following case, <topicref href="foo.dita"/>, the <topicref> metadata is copied only to the first topic found in foo.dita. An alternative would be to copy metadata to all topics found in foo.dita.

Conditional processing

  • Conditional processing is also applied to the information (e.g. <title>, <metadata>) contained in a map. However, only the exclude action will work. The flag action does not work in this context.
  • Any attribute (that is, not only @audience, @platform, @product, @rev, @otherprops, @deliveryTarget and attributes specialized from @props) may be used to filter or flag an element. For example, the @status attribute may be used to highlight changes. See below.
  • Subject scheme maps, which should be used to validate attribute values and also to implement smarter conditional processing, are currently ignored.
  • If a map directly contains multiple <ditavalref> elements, all <ditavalref> elements but the first one are ignored. When this is the case, a warning is reported, though.
  • The externally specified DITAVAL file is combined with the <ditavalref> element, if any, which is a direct child of a map.
  • <ditavalref> error conditions Opens in new window are not detected.
  • In a DITAVAL file, action="passthrough" Opens in new window is not supported.

Flagging contents

  • Only the following elements (and, of course, their specializations) can be flagged without restrictions: <topic>, <p>, <lq>, <note>, <dl>, <ul>, <ol>, <sl>, <pre>, <lines>, <fig>, <object>, <table>, <simpletable>, <section>, <example>, <ph>, <term>, <xref>, <cite>, <q>, <boolean>, <state>, <keyword>, <tm>, <image>, <foreign>.
    Any other element (<li>, <dlentry>, <step>, <stentry>, etc) is just given some of the colors and font styles, if any, specified by the flagging elements and attributes found in the .ditaval file.
  • In a .ditaval file, attribute style="double-underline" is processed as if it were underline.
  • In a .ditaval file, attribute style="line-through" is supported in addition to underline and overline.
  • The @status attribute may be used to highlight changes. Example:
    $ ditac -filter status.ditaval doc.pdf doc.ditamap
    where file status.ditaval contains:
    <val>
      <prop action="flag" att="status" backcolor="#FFFF99" style="underline"
            val="new"/>
    
      <prop action="flag" att="status" backcolor="#99FF99" val="changed"/>
    
      <prop action="flag" att="status" backcolor="#FF7F7F" style="line-through"
            val="deleted"/>
    </val>
    and where doc.ditamap references a topic containing for example:
    <p>A paragraph containing <ph status="new">new text</ph>, 
    <ph status="changed">changed text</ph>, 
    <ph status="deleted">deleted text</ph>.</p>
    ...
    <p status="new">New paragraph.</p>
    ...
    <ul status="changed">
      <li>First item in changed <tt>ul</tt>.</li>
      <li><p>Second item.</p>
      <p status="deleted">Deleted paragraph.</p></li>
      <li>Third item.</li>
    </ul>
  • In a .ditaval file, the value of the @changebar attribute of the <revprop> element, has the following syntax:
    changebar -> prop [ S ';' S prop ]+
    
    prop -> prop_name ':' S prop_value
    The style properties supported there are:
    Name Value Default Description
    color <color> The value of the color property. See XSL 1.1 property change-bar-color.
    offset <length> 6pt See XSL 1.1 property change-bar-offset.
    placement start | end | left | right | inside | outside | alternate start See XSL 1.1 property change-bar-placement.
    style <border-style> solid See XSL 1.1 property change-bar-style.
    width <border-width> medium See XSL 1.1 property change-bar-width.
    Example:
    $ ditac -filter changebar.ditaval doc.pdf doc.ditamap
    where file changebar.ditaval contains:
    <val>
      <revprop action="flag" val="2.1"
        changebar="style: double; width: 3px; placement: start;" ></revprop>
    </val>
    and where doc.ditamap references a topic containing for example:
    ...
    <fig rev="2.1">
        <title>The logo of ACME corp.</title>
        <image href="acme_logo.png"/>
    </fig>
    ...
  • Change bars are implemented by only a few XSL-FO 1.1 processors, namely RenderX XEP Opens in new window and Antenna House Formatter Opens in new window. For any other XSL-FO processor (e.g. Apache FOP Opens in new window, XMLmind XSL-FO Converter Opens in new window) and also for all XHTML-based output formats (e.g. EPUB, Web Help), change bars are emulated using left or right borders. This emulation may give poor results when a change bar is added to a table.

Generating links

  • Attribute @collection-type, whatever its value, is ignored inside the <reltable> element.
  • Ditac cannot generate “smart labels” for related links. The label is always "Related Links". It could have been "Related Concepts", "Related Reference" or even something determined using what is specified in the <title> child element of a <relcolspec> element.

Chunking

  • The "to-navigation" chunk value is ignored.
  • When the @copy-to attribute is used to specify an URI, the parent path part (e.g. "foo" in "foo/bar.htm") and the extension part (e.g. ".htm" in "foo/bar.htm") are ignored. Only the ``root name'' (e.g. "bar" in "foo/bar.htm") is taken into account during the processing of the map.
  • The default chunking policy is by-document.
  • When the deliverable targets a print media, all chunk specifications are removed and a chunk="to-content" attribute is added to the root element of the map.

Other limitations and specificities

  • There are several limitations and inconsistencies when working with files containing multiple topics and/or nested topics.
    For example, let's suppose a map contains the following <topicref>s, where multi.dita contains multiple topics (first topic being t1, second topic being t2), each topic possibly containing nested topics.
    <topicref href="multi.dita"/>
    <topicref href="multi.dita"/>
    <topicref href="multi.dita#t1"/>
    <topicref href="multi.dita#t2"/>
    • As expected, the first <topicref> pulls all the topics, including nested ones, contained in multi.dita. However parent, child, sibling, etc, related links will not be automatically generated for these topics.
    • The second <topicref> pulls a copy of all the topics, including nested ones, contained in multi.dita. The third <topicref> pulls a copy of topic t1 (excluding nested topics). The fourth <topicref> is not detected as pulling a copy of topic t2. Therefore the fourth <topicref> does nothing at all, as topic t2 has already being pulled into the deliverable (by the first <topicref>).
  • The following <topicref> elements are not treated differently from the others: <topicset>, <topicsetref>.
  • The following <bookmap> elements: <abbrevlist>, <amendments>, <appendices>, <appendix>, <bibliolist>, <bookabstract>, <booklist>, <chapter>, <colophon>, <dedication>, <draftintro>, <figurelist>, <examplelist>, <equationlist>, <glossarylist>, <indexlist>, <notices>, <part>, <preface>, <tablelist>, <toc>, <trademarklist>, are considered to have an implicit title when
    • they have no @href attribute,
    • and they have no explicit title,
    • and they contain one or more <topicref> (of any type) child elements.
    For example:
    <glossarylist>
      <topicref href="term1.dita"/>
      <topicref href="term2.dita"/>
      <topicref href="term3.dita"/>
    </glossarylist>
    is processed as if it was:
    <glossarylist navtitle="Glossary">
      <topicref href="term1.dita"/>
      <topicref href="term2.dita"/>
      <topicref href="term3.dita"/>
    </glossarylist>
  • All attributes and elements — map/@anchorref, <anchorref>, <anchor>, <navref> — related to runtime integration of maps are ignored.
  • Ditac reports a "topicB, href points outside processed topics" warning when topicA references topicB and topicB is not referenced in the map. In order to suppress this warning, add to the map a <topicref> having attribute toc="no" and pointing to topicB.
  • Convenience element <glossref> Opens in new window cannot be used with ditac without setting some of its attributes. Example:
    <glossref href="ONE.dita" keys="key_ONE"/>
    is strictly equivalent to:
    <topicref href="ONE.dita" keys="key_ONE" linking="none" print="no"
              toc="no" search="no"/>
    Notice default attribute print="no". Therefore, when generating PDF, such <glossref> is discarded at a very early stage by ditac. The consequence is that each occurrence of <abbreviated-form keyref="key_ONE"/> will cause ditac to report a "cannot resolve keyref" warning. The workaround is to simply avoid using <glossref> and to stick to <topicref> with a @keys attribute.