New features in the DITA 1.1 Standard DITA 1.1 was released as a public standard in 2007. The following items in the DITA 1.1 standard may be useful for users of the DITA Open Toolkit. Graphic scaling improvement

Graphic scaling improvement is an enhanced feature that DITA Open Toolkit 1.3 provides. DITA OT 1.3 supports this feature in the transformation for different outputs, such as HTML, XHTML, PDF, and FO. This feature is not applicable in RTF output.

  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

To implement this feature, you must first meet the following prerequisites:

  • Install and configure the DITA Open Toolkit 1.3 successfully.
  • Ensure that the image file referred to by the <image> tag exists.

In DITA 1.1, there are some attributes that you can use to set the actual display size of the pictures in the <image> tag, such as "width", "height", and so on.

You can set the actual display size of the image in the output by taking the following steps:

  1. Specify the height and width of the picture in the "height" and "width" attributes of the <image> tag, for example, <image height="80" width="60" href="a.jpg"/>
  2. (Optional) Specify the metric of the length in the height and width attributes fields, for example, <image height="80pc" width="60pc" href="a.jpg"/>. The metrics currently supported are: px, pc, pt, in, cm, mm, em. The default is px.If you do not specify the metric of the length, the toolkit will use the default metric, px.
  3. Run the transformation to generate the outputs, such as xhtml, HTML, and FO, that support graphic scaling.
In the final output, you can see the image displayed in the size that you expected. As in this example, the picture will be displayed by 80 pt in height and 60 pt in width.

You can also use the scaling function in setting the actual display size of the image in the output by taking the following steps:

  1. Specify the height and width of the picture in the "height" and "width" attributes of the <image> tag, and the metric of the length.
  2. Specify the scale rate in the scale attribute after you specify the height and width for the image, for example, <image height="80pc" width="60pc" href="a.jpg" scale="0.8"/>. Scale="0.8" means the picture in the output will be displayed at 80% of the size that you specified by height and width.
  3. Run the transformation to generate the outputs that support image scaling, such as xhtml, HTML, and FO.
In the final output, you can see the image displayed in the size that you expected. As in this example, the picture will be displayed by 64 pt in height and 48 pt in width.

Extensible metadata attributes

OASIS DITA 1.1 provides the DITA architects with an enhanced feature, extensible metadata attributes. If the architects want to achieve multiple purposes in one attribute, especially in a selective attribute, they can use the extensible metadata attributes.

  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.
Example

The following example illustrates how people of different roles use the extensible metadata attributes in DITA 1.1.

  • As a DITA architect of a team, you can perform the following actions:

    1. Define new attributes that the team needs, for example, "proglanguage".
    2. Express each new attribute as a separate domain package, for example, proglanguage.mod, with the new attribute specialized from the "props" attribute.
    3. Integrate the domain packages into the authoring DTDs or schemas:
      1. Redefine the "props" attribute entity to include the "proglanguage" attribute. Similarly, you can redefine element entities to integrate new domain elements.
      2. Add the new attribute domain to the list of domains in the domains attribute, preceded by an "a", for example, domains="a(props proglanguage)".

  • As an author, you can perform the following actions:
    1. Add values to the new attributes of an element.
    2. Define values in the DITA filter file.
    3. Transform the DITA source files to remove or flag the content based on the new attributes, for example, flagging all proglanguage="Java"

    After you perform these actions, another user can reuse the content.

    A specialization-unaware trademarking tool requires generalization of the contributed content. If the user runs all the content through the tool, the content is processed and filtered against the new attributes after the generalization. The new attributes are now collapsed into the "props" attribute.

    1. The generalization turned proglanguage="Java" into props="proglanguage(Java)".
    2. The conditional processing transform recognizes the new form as equivalent to the old, and the instruction "flag all proglanguage=java" operates on either props="proglanguage(Java)" or proglanguage="Java".

New element <abstract>

You can now use a new element <abstract> in DITA topics. The <abstract> element can include complex markups besides the <shortdesc> element. You can put the <shortdesc> element inside the <abstract> element, together with many other elements. The following examples illustrate how you can use the <abstract> element..

If you use several <shortdesc> elements inside the <abstract> element, they will be concatenated when pulled for hover help. After you format the source files, the content inside the <abstract> element will be transformed into normal text.

  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

Examples

Example 1In DITA 1.0, you can only use the <shortdesc> element that cannot contain the <p> element. <shortdesc>This is a short description in DITA 1.0. It <b>cannot</b> contain paragraphs.</shortdesc>

Example 2This example illustrates how you can use different elements besides <shortdesc> inside the <abstract> element, and apply different styles to the text inside the <abstract> element. <abstract> <shortdesc>This is the short description</shortdesc> <ol> <li>This is a <i>list</i>.</li> </ol> <p>This is a <b>paragraph</b>.</p> <codeblock>Here are some codes.</codeblock> <filepath>This is the file path.</filepath> </abstract>

Example 3This example illustrates how you can use both the <shortdesc> element and plain text inside the <abstract> element. <abstract><shortdesc>This topic is about short description.</shortdesc>. Short description is very important, so read more.</abstract>

New element <data>

In DITA 1.1, you can use new element, <data>. This element and the content inside it is ignored in the transformation process of DITA files.

  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

As an author, when you create DITA files, you can add the <data> element, and put content inside it. When you transform the DITA files to the output that you want, the transformation ignores the <data> element and any content inside.

As a specializer, when you specialize the <data> element, and put information inside the specialized element, you can create a transform override to use the information.

Indexing

DITA 1.1 supports the following new indexing elements:

  • <index-see>
  • <index-see-also>
  • <index-sort-as>
  • <index-range-start>
  • <index-range-end>
  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

See and See Also indexing elements

In DITA 1.0, you cannot specify the <see> and <see also> index entries by using the current <indexterm> element. The DITA1.1 standard introduces the following new child elements for <indexterm> that support this functionality:

  • index-see
  • index-see-also

For example, you can add an index entry, as illustrated in the following text in the DITA source file: <indexterm>computer <index-see>monitor</index-see> <index-see-also>Illustration</index-see-also> </indexterm> Then, if you generate a PDF output with the indexing function enabled, you can see the following index entries in the PDF output: computer 43 See monitor See also IllustrationThe "monitor" and "Illustration" entries after "see" and "see also" will not be links to the "monitor" and "Illustration" index entries in a PDF output.

If you generate HTML output using the same source file, you can get the following index entries; however, instead of displaying page numbers, the HTML file display the terms after "see" and "see also" as hyperlinks. The "Illustration" hyperlink points to the index entry for "Illustration" under "I".Computer See monitor See also Illustration

Index entries will only be processed when you generate HTMLHelp and JavaHelp. For HTMLHelp and JavaHelp, the index contains an entry that uses the text "See xxx" or "See also xxx". The "See xxx" or "See also xxx" index entries will link to their parent index term.

  • For HTML output, indexing is ignored.
  • For PDF output, you must enable indexing using the FO plugin provided by Idiom.

For example, if you put the following content in the source file, <indexterm>computer <index-see>monitor</index-see> </indexterm> the output is as follows: computer See monitor

Sort order indexing elements

With the DITA 1.1 standard, you can specify a sort phrase and sort index entries under the sort phrase. This feature provides you with the flexibility to sort an index entry in a different way. Typically you can disregard insignificant leading text, such as punctuation or words like "the" or "a". If you want to sort <data> under the letter D rather than the character "<", you can include such an entry under both the punctuation heading and the letter D. Thus, there can be two index entry directives differentiated only by the sort order.

For example, if you put the following content in the source file, <indexterm>data<index-sort-as>key</index-sort-as></indexterm> <indexterm>indextest<index-sort-as>abc</index-sort-as></indexterm> the output should be: indextest data

If you have written an XML book with many punctuation-laden entries in its index, you can use the <index-sort-as> element to specify how the sorting method of the entries if the punctuation marks are eliminated. For example, <data> is always displayed as an entry <data> in the index term under the letter D; otherwise, all the entries with punctuations will be sorted under "<".

Here is another example. In a translation project, a document needs to be translated into Japanese. Many of the index entries contain kanji, which need to be sorted in phonetic order. The translators, who can understand the language and see the entry in its context, can insert the <index-sort-as> elements into the <indexterm> elements as part of their localization work.

Page-range indexing elements

In DITA OT 1.3, you can indicate page ranges instead of individual references over consecutive pages. Page ranges indicate where the index entry links to an extended discussion that goes over a number of pages. This is typically manifested as a page range like 34-36. This is distinguished from individual references over consecutive pages (34, 35, 36). The page-range indexing function is enabled when you use the FO plugin.

For example, you can add a page spanning index entry: <indexterm>DITA<index-range-start/></indexterm>. Later in the same topic, you can add a range terminating marker: <indexterm>DITA<index-range-end/></indexterm>. This spans 4 pages on the paper, as illustrated in the following example.DITA, 46-49If you generate HTMLHelp, JavaHelp, and XHTML outputs, the page-range indexing elements are ignored.

Supporting ICU in index sorting

With enabled ICU interface, DITA Open Toolkit 1.3 helps you get correctly sorted index output for different languages.

During normal transformation, the toolkit tries to find if there are ICU classes inside the classpath element. If ICU exists, the toolkit uses ICU's Collator class to do the comparing and sorting work. If no ICU is found, the toolkit will use JDK's Collator class to do the comparing and sorting work. ICU is packed in the big package in DITA OT 1.3

Supporting foreign content vocabulary

In DITA 1.1, you can use the <unknown> element to incorporate existing standard vocabularies for special content, like MathML and SVG, as inline objects.

  • Because OASIS DITA 1.1 is not yet an approved standard as of the release of DITA OT 1.3, the functionality described here should be considered a preview capability.
  • The specification and the defined functions that need to be supported can change by the time OASIS formally approves DITA 1.1.

As an author, when you create DITA files, you can add the <unknown> element, and put content inside it. The <unknown> element and any content inside it is ignored when you transform the DITA files to your desired output.

As a specializer, when you specialize the <unknown> element, and then put information inside the specialized element, you can create a transform override that allows the information to appear correctly in the output.