Appendix C. Limitations and implementation specificities

§ Conversion to XHTML and XSL-FO

The following elements are ignored:
- the <syntaxdiagram> element and all its descendant elements;
- <ux-window> ;
- <sort-as> .
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:
- Attribute <entry>/@rotate is not supported.
- Conversion to XHTML:
  - Attribute <table>/@orient="land" (landscape table) is not supported.
  - 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 <table>/@orient="land" (landscape table) is supported. However, except when the XSL-FO processor being invoked by ditac is XMLmind XSL-FO Converter v6.2+ , the landscape table must have few enough rows to fit onto one page. When this is not the case, the last rows of the landscape table will simply not appear in the output.
  - 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.
Entries automatically generated by ditac for <toc>, <tablelist>, <figurelist>, <examplelist>, <equationlist> and <indexlist> only contain plain text. For example, if a topic title is "<title>The Java<sup>TM</sup> <b>Spring</b> framework</title>", then the corresponding TOC entry contains "The JavaTM Spring framework".
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 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.
By default, the character encoding of the text file included using a <coderef> element is automatically determined by ditac (e.g. by examining the BOM or <?xml encoding="XXX"?>). You may specify this character encoding explicitly by adding a format="text; charset=XXX" attribute to the <coderef> element. Example: <coderef format="text; charset=US-ASCII" href="../src/sieve.cpp"/>.

§ 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.

§ Subject scheme maps

XMLmind DITA Converter supports all the features documented in "2.2.3 Subject scheme maps and their usage" when these features are related to attribute values.

Only the following useful subset of the grammar of subject scheme maps is supported by ditac. Any other subject scheme element

is silently ignored:

<subjectScheme>
  Content: [ subjectdef | enumerationdef | schemeref ]*
</subjectScheme>

<subjectdef
  keys = name of a set of attribute values OR an attribute value 
  OR
  keyref = name of a set of attribute values OR an attribute value
  navtitle = description of this subjectdef
>
  Content: [ <topicmeta>
               <navtitle>description of this subjectdef</navtitle>
             </topicmeta> ]?
           [ subjectdef ]*
</subjectdef>

<enumerationdef>
  Content: [ elementdef ]* 
           attributedef 
           <subjectdef
             keyref = name of a set of attribute values
                      (keyref absent means:
                       don't use this attribute)
           />
</enumerationdef>

<elementdef
  name = element qualified name
/>

<attributedef
  name = attribute qualified name
/>

<schemeref
  href = location of another subject scheme map
/>

All the subject scheme maps referenced in the map⁽¹⁾ to be converted and in all its submaps are loaded in turn and their contents are merged as if a single subject scheme map was specified at the very beginning of the main map.
It's also possible to specify which subject scheme map to use by the means of the -attrvalues and -defaultattrvalues command-line options.
Attribute groups are fully supported both for attribute value validation and when filtering and flagging. Example, some of the values declared for attribute @platform:
```
<subjectdef keys="macos"/>
<subjectdef keys="linux">
  <subjectdef keys="redhat"/>
  <subjectdef keys="ubuntu"/>
</subjectdef>
```
A validation error will be reported for attribute platform="linux(redhat debian)" because "debian" has not been declared. A validation error will be reported for attribute platform="macos(redhat)" because "redhat" is not a kind of "macos".

§ 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 are not detected.
In a DITAVAL file, action="passthrough" 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 the following processors: Apache FOP , RenderX XEP and Antenna House Formatter . For any other XSL-FO processor (e.g. XMLmind XSL-FO Converter ) 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

<topicref> elements found inside a <reltable> do not “pull” the corresponding topics. In other words, a <reltable> cannot be used to add some content to a deliverable. With ditac, a <reltable> is just used to create links between topics which are already part of the deliverable.
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> 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.