source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/readme/DITA-h2d.xml@ 99507

<?xml version="1.0" encoding="utf-8"?>
<!-- This file is part of the DITA Open Toolkit project hosted on 
     Sourceforge.net. See the accompanying license.txt file for 
     applicable licenses.-->
<!-- (c) Copyright IBM Corp. 2005, 2011 All Rights Reserved. -->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="h2d" xml:lang="en-us">
<title>Migrating HTML to DITA</title>
<shortdesc>The HTML to DITA migration tool ships in the <filepath>plugins</filepath> directory of
    the toolkit, and does not make use of the common toolkit processing for DITA
    content.</shortdesc>
<conbody>
<p>The DITA Open Toolkit release 1.2 or above provides a HTML to DITA migration tool, which migrates
      HTML files to DITA files. This migration tool originally comes from the developerWorks
      publication of Robert D. Anderson's how-to articles with the original h2d code. This migration
      tool is under <filepath>plugins\h2d</filepath> directory. You can use it separately because it
      is not integrated into the main transformation of toolkit. The version in the toolkit is more
      recent, but the articles should be referenced for information on details of the program, as
      well as for information on how to extend it. There are links to the articles at the bottom of
      this page.</p>
<section>             <title>Preconditions</title>             <p>The
preconditions to be considered before using the migration        
         tool are listed below:</p>             <ul>
<li>The HTML file content must be divided among concepts,        
             tasks, and reference articles. If not, the HTML files
                     should be reworked before migrating.</li>
<li>This migration tool is intended for topics. The HTML page    
                 should contain a single section without any nested
                     sections.</li>
<li>DITA architecture is focused on topics, information that is  
                   written for books needs to be redesigned in order
to fit                      into a topic-based archiecture.</li>
<li>This migration utility only works with valid XHTML files,    
                 HTML files must be cleaned up using HTML Tidy or
other                      utility before processing.</li>
</ul>         </section>
<!--section>
            <title>Running examples</title>
            <p>You can use the Ant script to migrate only one HTML file or all 
                the HTML files in same directory each time. See <xref 
                href="DITA-h2d-ant.xml#h2d-ant"></xref> for more 
                details.</p>
            <p>You can also use the Java command for migration. See <xref 
                href="DITA-h2d-java.xml#h2d-java"></xref> for more 
                details.</p>
        </section-->
<section>             <title>Post conditions</title>             <p>There
are also some post conditions to consider after                  processing:</p> 
           <ul>
<li>In some case, the tool cannot determine the correct way to migrate,
it places the contents in a &lt;required-cleanup&gt; element, you
should fix such elements in the output DITA files.</li>
<li> Check the output DITA files. Compare them with the source   
                  HTML files and check if both contents are equivalent.</li>
</ul>         </section>
<section>             <title>Known limitations</title>           
 <ol conref="DITA-limitations.xml#limitations/html2dita-limitations">
<li></li>
</ol>         </section>
<section>             <title>Extension points</title>             <p>The
HTML2DITA migration tool helps extension in the following        
         listed ways:</p>             <ul>
<li>The <codeph>genidattridbute</codeph> template can be         
            overridden to change the method for creating the topic
ID.                      </li>
<li>The <codeph>gentitlealts</codeph> template can be            
         overridden to change the ways of title generation.</li>
<li>Override respond section in the tool to preserve the         
            semantic of source, in case if the &lt;div> or &lt;span>
                     element is used in regular structures.</li>
<li>You can also migrate to another specialized DTD by           
          overriding the original template base on the specific DTD
                     and your required output.</li>
</ul>         </section>
</conbody>
<related-links>
<link format="html"
href="http://www.ibm.com/developerworks/xml/library/x-dita8a/"
scope="external"><linktext>Migrating HTML to DITA, part 1</linktext>
</link>
<link format="html"
href="http://www.ibm.com/developerworks/xml/library/x-dita8b/"
scope="external"><linktext>Migrating HTML to DITA, part 2</linktext>
</link>
</related-links>
</concept>