source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/readme/DITA1.1-newfeature.xml@ 99012

<?xml version="1.0" encoding="UTF-8"?>
<!--Arbortext, Inc., 1988-2010, v.4002-->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
 "concept.dtd">
<concept id="newfeaturesinthedita1.1standard" xml:lang="en-us">
<title>New features in the DITA 1.1 Standard</title>
<shortdesc>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.</shortdesc>
<conbody></conbody>
<concept id="graphicscalingimprovement" xml:lang="en-us">
<title>Graphic scaling improvement</title>
<conbody>
<p>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.<note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                        can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note></p>
<p>To implement this feature, you must first meet the following prerequisites:<ul>
<li>Install and configure the DITA Open Toolkit 1.3 successfully. </li>
<li>Ensure that the image file referred to by the <codeph>&lt;image></codeph> tag
                    exists.</li>
</ul></p>
<p>In DITA 1.1, there are some attributes that you can use to set
the actual                 display size of the pictures in the <codeph>&lt;image></codeph> tag,
such                 as "width", "height", and so on. </p>
<p>You can set the actual display size of the image in the output
by taking                 the following steps:<ol>
<li>Specify the height and width of the picture in the "height" and
"width"                         attributes of the <codeph>&lt;image></codeph> tag,
for example, <codeph>&lt;image                             height="80"
width="60" href="a.jpg"/></codeph></li>
<li rev="r3">(Optional) Specify the metric of the length in the height
and                         width attributes fields, for example, <codeph>&lt;image
height="80pc" width="60pc"                             href="a.jpg"/></codeph>.
The metrics currently supported are: px, pc, pt,                 
       in, cm, mm, em. The default is px.<note rev="r3">If you do
not specify the                             metric of the length,
the toolkit will use the default metric, px. </note></li>
<li>Run the transformation to generate the outputs, such as xhtml,
HTML, and                         FO, that support graphic scaling. </li>
</ol>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.</p>
<p rev="r1">You can also use the scaling function in setting the actual
display                 size of the image in the output by taking
the following steps:<ol>
<li>Specify the height and width of the picture in the "height" and
"width"                         attributes of the <codeph>&lt;image></codeph> tag,
and the metric of the length.</li>
<li>Specify the scale rate in the scale attribute after you specify
the height                         and width for the image, for example, <codeph>&lt;image
height="80pc" width="60pc"                             href="a.jpg"
scale="0.8"/></codeph>. Scale="0.8" means the picture in the     
                   output will be displayed at 80% of the size that
you specified by height and                         width. </li>
<li>Run the transformation to generate the outputs that support image
scaling,                         such as xhtml, HTML, and FO.</li>
</ol>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.</p>
</conbody>
</concept>
<concept id="extensiblemetadataattributes" xml:lang="en-us">
<title>Extensible metadata attributes</title>
<conbody>
<p> 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.</p>
<note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                    can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note>
<example><title>Example</title><p>The following example illustrates
how people                 of different roles use the extensible metadata
attributes in DITA 1.1.</p><ul>
<li>As a DITA architect of a team, you can perform the following actions:<p><ol>
<li>Define new attributes that the team needs, for example, "proglanguage". </li>
<li>Express each new attribute as a separate domain package, for example,
                            proglanguage.mod, with the new attribute
specialized from the "props" attribute.</li>
<li>Integrate the domain packages into the authoring DTDs or schemas:
 <ol>
<li> Redefine the "props" attribute entity to include the "proglanguage"
attribute.                                 Similarly, you can redefine
element entities to integrate new domain elements.</li>
<li rev="r4">Add the new attribute domain to the list of domains in
the domains                                 attribute, preceded by
an "a", for example, <codeph>domains="a(props proglanguage)"</codeph>.</li>
</ol></li>
</ol></p></li>
<li>As an author, you can perform the following actions: <ol>
<li>Add values to the new attributes of an element.</li>
<li>Define values in the DITA filter file.</li>
<li>Transform the DITA source files to remove or flag the content
based on                             the new attributes, for example,
flagging all <codeph>proglanguage="Java"</codeph></li>
</ol><p>After you perform these actions, another user can reuse the
content. </p><p>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.
 <ol>
<li>The generalization turned <codeph>proglanguage="Java"</codeph> into <codeph>props="proglanguage(Java)"</codeph>.</li>
<li>The conditional processing transform recognizes the new form as
equivalent                                 to the old, and the instruction
"<codeph>flag all proglanguage=java</codeph>"                    
            operates on either <codeph>props="proglanguage(Java)"</codeph> or <codeph>proglanguage="Java"</codeph>.</li>
</ol></p></li>
</ul></example>
</conbody>
</concept>
<concept id="newelementabstract" xml:lang="en-us">
<title>New element &lt;abstract></title>
<conbody>
<p>You can now use a new element &lt;abstract> in DITA topics. The &lt;abstract>
                element can include complex markups besides the &lt;shortdesc>
element. You                 can put the &lt;shortdesc> element inside
the &lt;abstract> element, together                 with many other
elements. The following examples illustrate how you can use      
          the &lt;abstract> element.. </p>
<p>If you use several &lt;shortdesc> elements inside the &lt;abstract>
element,                 they will be concatenated when pulled for
hover help.  After you format the                 source files, the
content inside the &lt;abstract> element will be transformed     
           into normal text. <note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                        can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note></p>
<example><title>Examples</title><p><lines><ph><b>Example 1</b></ph></lines>In
                DITA 1.0, you can only use the &lt;shortdesc> element
that cannot contain                 the &lt;p> element. <codeblock> &lt;shortdesc>This is a short description in DITA 1.0. It &lt;b>cannot&lt;/b> contain paragraphs.&lt;/shortdesc></codeblock></p><p><lines><ph><b>Example 2</b></ph></lines>This
example illustrates how                     you can use different
elements besides &lt;shortdesc> inside the &lt;abstract>         
           element, and apply different styles to the text inside
the &lt;abstract> element.<codeblock rev="r2">    &lt;abstract>
                        &lt;shortdesc>This is the short description&lt;/shortdesc>
                        &lt;ol>
                        &lt;li>This is a &lt;i>list&lt;/i>.&lt;/li>
                        &lt;/ol>
                        &lt;p>This is a &lt;b>paragraph&lt;/b>.&lt;/p>
                        &lt;codeblock>Here are some codes.&lt;/codeblock>
                        &lt;filepath>This is the file path.&lt;/filepath>
                        &lt;/abstract></codeblock></p><p><lines><ph><b>Example 3</b></ph></lines>This
                            example illustrates how you can use both
the &lt;shortdesc> element and plain                             text
inside the &lt;abstract> element.<codeblock> &lt;abstract>&lt;shortdesc>This topic is about short description.&lt;/shortdesc>. 
                                Short description is very important, so read more.&lt;/abstract></codeblock></p></example>
</conbody>
</concept>
<concept id="newelementdata" xml:lang="en-us">
<title>New element &lt;data></title>
<conbody>
<p>In DITA 1.1, you can use new element, &lt;data>. This element and
the content                 inside it is ignored in the transformation
process of DITA files.<note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                        can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note></p>
<p>As an author, when you create DITA files, you can add the &lt;data>
element,                 and put content inside it. When you transform
the DITA files to the output                 that you want, the transformation
ignores the &lt;data> element and any content                 inside. </p>
<p rev="r3">As a specializer, when you specialize the &lt;data> element,
and                 put information inside the specialized element,
you can create a transform                 override to use the information. </p>
</conbody>
</concept>
<concept id="indexing" xml:lang="en-us">
<title>Indexing</title>
<conbody>
<p>DITA 1.1 supports the following new indexing elements:<ul>
<li>&lt;index-see></li>
<li>&lt;index-see-also></li>
<li>&lt;index-sort-as></li>
<li>&lt;index-range-start></li>
<li>&lt;index-range-end></li>
</ul><note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                    can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note></p>
<section><title>See and See Also indexing elements</title><p>In DITA
1.0,                 you cannot specify the &lt;see> and &lt;see also>
index entries by using the                 current &lt;indexterm>
element. The DITA1.1 standard introduces the following           
     new child elements for &lt;indexterm> that support this functionality:</p><ul>
<li>index-see</li>
<li>index-see-also</li>
</ul><p>For example, you can add an index entry, as illustrated in
the following                     text in the DITA source file: <codeblock>&lt;indexterm>computer
                        &lt;index-see>monitor&lt;/index-see>
                        &lt;index-see-also>Illustration&lt;/index-see-also> 
                        &lt;/indexterm>
                    </codeblock>Then, if you generate a PDF output
with the indexing function                     enabled, you can see
the following index entries in the PDF output:<screen>
                        computer 43
                        See monitor
                        See also Illustration</screen>The "monitor"
and "Illustration" entries                     after "see" and "see
also" will not be links to the "monitor" and "Illustration"      
              index entries in a PDF output.</p><required-cleanup><!--Deleted per Marshall--><p>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".<screen><u>Computer</u>
                        See <u>monitor</u>
                        See also <u>Illustration</u>
                    </screen></p></required-cleanup><p rev="r2">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<ph rev="r3"> will link to their parent        
                    index term.</ph> <note rev="r3"><ul>
<li>For HTML output, indexing is ignored. </li>
<li>For PDF output, you must enable indexing using the FO plugin provided
                                    by Idiom. </li>
</ul></note></p><p>For example, if you put the following content in
the source                                 file, <codeblock>&lt;indexterm>computer
                                    &lt;index-see>monitor&lt;/index-see>
                                    &lt;/indexterm></codeblock> the
output is as follows: <screen>
                                        computer
                                        See monitor</screen></p></section>
<section><title>Sort order indexing elements</title><p>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 &lt;data> under                 the letter
D rather than the character "&lt;", 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. </p><p>For example,                     if
you put the following content in the source file,<codeblock rev="r3">  &lt;indexterm>data&lt;index-sort-as>key&lt;/index-sort-as>&lt;/indexterm>
                        &lt;indexterm>indextest&lt;index-sort-as>abc&lt;/index-sort-as>&lt;/indexterm>
                    </codeblock> the output should be:<msgblock>
                        indextest
                        data</msgblock></p><p rev="r3">If you have
written an XML book with many punctuation-laden                  
          entries in its index, you can use the &lt;index-sort-as>
element to specify                             how the sorting method
of the entries if the punctuation marks are eliminated.          
                  For example, <codeph>&lt;data></codeph> is always
displayed as an entry &lt;data>                             in the
index term under the letter D; otherwise, all the entries with punctuations
                            will be sorted under "&lt;". </p><p>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 <codeph>&lt;index-sort-as></codeph> elements into the <codeph>&lt;indexterm></codeph> elements
                                as part of their localization work. </p></section>
<section><title>Page-range indexing elements</title><p>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.</p><p>For example, you can add
a page spanning index entry: <codeblock>&lt;indexterm>DITA&lt;index-range-start/>&lt;/indexterm></codeblock>.
Later in the same topic, you can add a range terminating marker: &lt;indexterm>DITA&lt;index-range-end/>&lt;/indexterm>.
                    This spans 4 pages on the paper, as illustrated
in the following example.<screen>DITA, 46-49</screen><note>If    
                    you generate HTMLHelp, JavaHelp, and XHTML outputs,
the page-range indexing                         elements are ignored. </note> </p></section>
<section><title>Supporting ICU in index sorting</title><p>With enabled
ICU                 interface, DITA Open Toolkit 1.3 helps you get
correctly sorted index output                 for different languages. </p><p>During
normal transformation, the toolkit                     tries to find
if there are ICU classes inside the <codeph>classpath</codeph> 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. <ph rev="r2">ICU
is packed in the big                         package in DITA OT 1.3</ph></p></section>
</conbody>
</concept>
<concept id="unknown" xml:lang="en-us">
<title>Supporting foreign content vocabulary</title>
<conbody>
<p>In DITA 1.1, you can use the &lt;unknown> element to incorporate
existing                 standard vocabularies for special content,
like MathML and SVG, as inline                 objects.  <note rev="r5"><ul>
<li>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 <i>preview</i> capability. </li>
<li>The specification and the defined functions that need to be supported
                        can change by the time OASIS formally approves
DITA 1.1.</li>
</ul></note></p>
<p>As an author, when you create DITA files, you can add the &lt;unknown>
                element, and put content inside it. The &lt;unknown>
element and any content                 inside it is ignored when
you transform the DITA files to your desired output. </p>
<p id="r" rev="r3">As a specializer, when you specialize the &lt;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. </p>
</conbody>
</concept>
</concept><?Pub Caret -3?>
<?Pub *0000020395?>