Diff for DITA 1.2 Specification - Building Specification Subsets

Tue, 2010-09-28 15:20 by StanDohertyTue, 2010-11-16 12:30 by StanDoherty
< previous diffnext diff >
Changes to Body
Line 2Line 2
 
<strong>WORK IN PROGRESS</strong>
 
<strong>WORK IN PROGRESS</strong>
 
</p>
 
</p>
  +
<h2>Background</h2>
  +
<hr />
  +
OASIS (soon) has released Version 1.2 of the OASIS Darwin Information Typing Architecture (DITA) specification developed by the OASIS DITA Technical Committee. Complete, OASIS-branded versions of the spceification are available for you to download at the following site:
 
<p>
 
<p>
-
This wiki page focuses on documenting how to download OASIS DITA 1.2 Language Specification sources and how to build the following subsets of that specification in the DITA Open Toolkit:
+
&nbsp;
 
</p>
 
</p>
-
<ul>
  
-
<li>Introduction (spec/introduction.ditamap)</li>
  
-
<li>Architectural Specification (spec/architectural-specification.ditamap) </li>
  
-
<li>Language Reference Specification (spec/language-reference.ditamap) </li>
  
-
<li>DITA Conformance Statement (spec/conformance.dita)</li>
  
-
<li>Non-normative Information (spec/non-normative-information.ditamap)</li>
  
-
</ul>
  
-
<h2>Downloading DITA 1.2 Specification Source Documents</h2>
  
-
<hr />
  
 
<p>
 
<p>
-
The most current DITA language specification source files for this testing = Monday, September 27, 2010.
+
http://dita.xml.org/news/dita-12-submitted-for-oasis-ballot
 
</p>
 
</p>
 
<p>
 
<p>
-
URL: . . .
+
In its complete form, this specification consists of the following separately buildable sections, each with its own DITA map:
 
</p>
 
</p>
  +
<ul>
  +
<li>Introduction (spec/introduction.ditamap)</li>
  +
<li>Architectural Specification (architectural-specification.ditamap) </li>
  +
<li>Language Reference Specification (language-reference.ditamap) </li>
  +
<li>DITA Conformance Statement (conformance.dita)</li>
  +
<li>Non-normative Information (non-normative-information.ditamap)</li>
  +
</ul>
 
<p>
 
<p>
-
&nbsp;
+
To build these specification subsets, you must install a build environment that is compliant with DITA Version 1.2 DTDs or schema. These DITA-compliant build environments are available as separate, downloadable packages or as components integrated with your DITA-compliant editor or content management system. For purposes of illustration, the build environment documented here consists of the following freely available, and uncustomized packages:
 
</p>
 
</p>
-
<h2>Building Subsets in the DITA Open Toolkit</h2>
+
<ul>
  +
<li>DITA Open Toolkit (DITA-OT1.5.2_m6 available at http://sourceforge.net/projects/dita-ot/)
  +
<ul>
  +
<li>MS HTMLHelp (.chm) transformation</li>
  +
<li>OpenOffice Document (.odt) transformation</li>
  +
<li>PDF (Idiom) transformation</li>
  +
<li>XHTML transformation</li>
  +
</ul>
  +
</li>
  +
<li>DITA for Publishers (D4P Version 0.9.10 available at http://sourceforge.net/projects/dita4publishers/)
  +
<ul>
  +
<li>ePub transformation</li>
  +
<li>Kindle transformation</li>
  +
</ul>
  +
</li>
  +
</ul>
  +
<h2>Basic Build Procedure</h2>
  +
<hr />
 
<p>
 
<p>
-
Here are the results of the testing with both the current production version of the DITA Open Toolkit (DITA-OT1.5.1_std) and the most current milestone build (DITA-OT1.5.2_m4).
+
To set up a default build environment, do the following.
 
</p>
 
</p>
 
<p>
 
<p>
 
&nbsp;
 
&nbsp;
 
</p>
 
</p>
-
<h3>DITA1.5.1_std</h3>
+
<ol>
  +
<li>Download and install the most current version of the DITA Open Toolkit.
  +
<p>
  +
For purposes of illustration, let's assume that you have installed the toolkit in a folder named DITA-OT1.5.2.
  +
</p>
  +
</li>
  +
<li>Download the DITA Version 1.2 specification sourec files from the following site.
  +
<p>
  +
http://docs.oasis-open.org/dita/v1.2/cs01/spec/DITA1.2-spec.zip
  +
</p>
  +
</li>
  +
<li>Unarchive these source files to a new folder at the root of the DITA Open Toolkit that you just installed.
  +
<p>
  +
For example, create a folder named DITA-OT1.5.2\dita1.2 and extract the source file to it.
  +
</p>
  +
</li>
  +
<li>Write one or more build scripts (typically ant) for specific transform types and specific specification subset maps.
  +
<ul>
  +
<li>Introduction (introduction.ditamap)</li>
  +
<li>Architectural Specification (architectural-specification.ditamap) </li>
  +
<li>Language Reference Specification (language-reference.ditamap) </li>
  +
<li>DITA Conformance Statement (conformance.dita)</li>
  +
<li>Non-normative Information (non-normative-information.ditamap)</li>
  +
</ul>
  +
<p>
  +
Modeling these build scripts on the ones in DITA-OT1.5.2\samples\ant_sample is a good starting place.
  +
</p>
  +
</li>
  +
<li>Run the build scripts.</li>
  +
</ol>
  +
  +
<h2>Basic Build Results and Notes</h2>
  +
<hr />
 
<p>
 
<p>
-
&nbsp;
+
The DITA Version 1.2 specification is a great resource for learning about new features such as , , and many others. That said, the specification is a complex and not all specification subsets build with a default DITA-OT configuration.
 
</p>
 
</p>
 
<table border="0">
 
<table border="0">
Line 38Line 88
 
<tr>
 
<tr>
 
<td>Specification Subet Map/Topic</td>
 
<td>Specification Subet Map/Topic</td>
-
<td>ePub</td>
+
<td>MS HTMLHelp</td>
-
<td>HTMLHelp</td>
+
<td>Open Office</td>
-
<td>PDF2 w/XEP</td>
+
<td>PDF</td>
 
<td>XHTML</td>
 
<td>XHTML</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/introduction.ditamap</td>
+
<td>introduction.ditamap</td>
-
<td>TBD</td>
+
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
Line 51Line 101
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/architectural-specification.ditamap</td>
+
<td>architectural-specification.ditamap</td>
-
<td>TBD</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
<td>Successful</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>
+
<td>language-reference.ditamap</td>
-
spec/language-reference.ditamap</td>
+
<td>Successful</td>
-
<td>TBD</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
<td>Successful</td>
-
<td>Failed*</td>
+
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/conformance.dita</td>
+
<td>conformance.dita</td>
-
<td>TBD</td>
+
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
Line 73Line 122
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/non-normative-information.ditamap</td>
+
<td>non-normative-information.ditamap</td>
-
<td>TBD</td>
+
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
Line 81Line 130
 
</tbody>
 
</tbody>
 
</table>
 
</table>
  +
<h3>Notes and limitations</h3>
  +
<ul>
  +
<li>Note-1: Java memory</li>
  +
<li>Note-2: TBD</li>
  +
<li>Note-3: TBD</li>
  +
<li>Note-4: TBD</li>
  +
</ul>
  +
<h2>Generating Specification Subsets for ePub and Kindle</h2>
  +
<hr />
 
<p>
 
<p>
-
&nbsp;
+
Incremental requirements:
 
</p>
 
</p>
-
<p>
+
<ul>
-
* Build failure error = Java Memory Heap
+
<li>ePub Plugin . . . </li>
-
</p>
+
<li>kindlegarden . . . </li>
-
<h3>DITA-OT1.5.2_m4</h3>
+
</ul>
 
<table border="0">
 
<table border="0">
 
<tbody>
 
<tbody>
Line 93Line 151
 
<td>Specification Subet Map/Topic</td>
 
<td>Specification Subet Map/Topic</td>
 
<td>ePub</td>
 
<td>ePub</td>
-
<td>HTMLHelp</td>
+
<td>Kindle</td>
-
<td>ODT</td>
+
-
<td>PDF2 w/o XEP</td>
+
-
<td>XHTML</td>
+
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/introduction.ditamap</td>
+
<td>introduction.ditamap</td>
-
<td>TBD</td>
+
-
<td>Successful</td>
+
-
<td>Successful</td>
+
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/architectural-specification.ditamap</td>
+
<td>architectural-specification.ditamap</td>
-
<td>TBD</td>
+
-
<td>Successful</td>
+
 
<td>Successful</td>
 
<td>Successful</td>
-
<td>Failed*</td>
  
 
<td>Successful</td>
 
<td>Successful</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>
+
<td>language-reference.ditamap</td>
-
spec/language-reference.ditamap</td>
+
-
<td>TBD</td>
+
 
<td>Successful</td>
 
<td>Successful</td>
-
<td>Successful</td>
  
-
<td>Failed*</td>
  
 
<td>Successful</td>
 
<td>Successful</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/conformance.dita</td>
+
<td>conformance.dita</td>
-
<td>TBD</td>
+
-
<td>Successful</td>
+
-
<td>Successful</td>
+
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
-
<td>spec/non-normative-information.ditamap</td>
+
<td>non-normative-information.ditamap</td>
-
<td>TBD</td>
+
-
<td>Successful</td>
+
-
<td>Successful</td>
+
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
 
<td>Successful</td>
Line 141Line 180
 
</tbody>
 
</tbody>
 
</table>
 
</table>
  +
<h2>Advanced Configurations</h2>
  +
<hr />
  +
<p>
  +
See &quot;Configuring your build environment to generate OASIS-styled PDFs&quot;.
  +
</p>
 
<p>
 
<p>
 
&nbsp;
 
&nbsp;
 
</p>
 
</p>
 
<p>
 
<p>
-
* Build failure error = Java Memory Heap
+
&nbsp;
 
</p>
 
</p>
 
<p>
 
<p>
Line 154Line 198
 
</p>
 
</p>
 
<p>
 
<p>
-
stan@modularwriting.com 
+
stan@modularwriting.com
 
</p>
 
</p>
 
<p>
 
<p>
Revision of Tue, 2010-11-16 12:30:

DITA 1.2 Specification - Building Specification Subsets

WORK IN PROGRESS

Background

OASIS (soon) has released Version 1.2 of the OASIS Darwin Information Typing Architecture (DITA) specification developed by the OASIS DITA Technical Committee. Complete, OASIS-branded versions of the spceification are available for you to download at the following site:

 

http://dita.xml.org/news/dita-12-submitted-for-oasis-ballot

In its complete form, this specification consists of the following separately buildable sections, each with its own DITA map:

  • Introduction (spec/introduction.ditamap)
  • Architectural Specification (architectural-specification.ditamap)
  • Language Reference Specification (language-reference.ditamap)
  • DITA Conformance Statement (conformance.dita)
  • Non-normative Information (non-normative-information.ditamap)

To build these specification subsets, you must install a build environment that is compliant with DITA Version 1.2 DTDs or schema. These DITA-compliant build environments are available as separate, downloadable packages or as components integrated with your DITA-compliant editor or content management system. For purposes of illustration, the build environment documented here consists of the following freely available, and uncustomized packages:

Basic Build Procedure

To set up a default build environment, do the following.

 

  1. Download and install the most current version of the DITA Open Toolkit.

    For purposes of illustration, let's assume that you have installed the toolkit in a folder named DITA-OT1.5.2.

  2. Download the DITA Version 1.2 specification sourec files from the following site.

    http://docs.oasis-open.org/dita/v1.2/cs01/spec/DITA1.2-spec.zip

  3. Unarchive these source files to a new folder at the root of the DITA Open Toolkit that you just installed.

    For example, create a folder named DITA-OT1.5.2\dita1.2 and extract the source file to it.

  4. Write one or more build scripts (typically ant) for specific transform types and specific specification subset maps.
    • Introduction (introduction.ditamap)
    • Architectural Specification (architectural-specification.ditamap)
    • Language Reference Specification (language-reference.ditamap)
    • DITA Conformance Statement (conformance.dita)
    • Non-normative Information (non-normative-information.ditamap)

    Modeling these build scripts on the ones in DITA-OT1.5.2\samples\ant_sample is a good starting place.

  5. Run the build scripts.

Basic Build Results and Notes

The DITA Version 1.2 specification is a great resource for learning about new features such as , , and many others. That said, the specification is a complex and not all specification subsets build with a default DITA-OT configuration.

Specification Subet Map/Topic MS HTMLHelp Open Office PDF XHTML
introduction.ditamap Successful Successful Successful Successful
architectural-specification.ditamap Successful Successful Successful Successful
language-reference.ditamap Successful Successful Successful Successful
conformance.dita Successful Successful Successful Successful
non-normative-information.ditamap Successful Successful Successful Successful

Notes and limitations

  • Note-1: Java memory
  • Note-2: TBD
  • Note-3: TBD
  • Note-4: TBD

Generating Specification Subsets for ePub and Kindle

Incremental requirements:

  • ePub Plugin . . .
  • kindlegarden . . .
Specification Subet Map/Topic ePub Kindle
introduction.ditamap Successful Successful
architectural-specification.ditamap Successful Successful
language-reference.ditamap Successful Successful
conformance.dita Successful Successful
non-normative-information.ditamap Successful Successful

Advanced Configurations

See "Configuring your build environment to generate OASIS-styled PDFs".

 

 

Stan Doherty (Stan@modularwriting.com)

OASIS DITA Technical Committee

stan@modularwriting.com

 

XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I

dita-bird_0.jpg

Hosted by:

OASIS

Sponsored by:

adobe-systems-incorporated_0_0_0.png

ibm.gif

Sponsored links:

Adobe DITA CCMS