<?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, 2006 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>
    <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 "demo\h2d" 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>
            <p>There are some known limitations within the current release, 
                please refer to <xref href="DITA-limitations.xml"/> 
                for detailed information.</p>
        </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>
        <section>
            <title>Additional information</title>
            <p>You can find the here original developerWorks publication via links below:</p>
            <ul>
                <li><xref href="http://www-128.ibm.com/developerworks/xml/library/x-dita8a" format="html" scope="external">Migrating HTML to DITA, Part 1: Simple steps to move from HTML to DITA</xref></li>
                <li><xref href="http://www-128.ibm.com/developerworks/xml/library/x-dita8b" format="html" scope="external">Migrating HTML to DITA, Part 2: Extend the migration for more robust results</xref></li>
            </ul>
        </section>
    </conbody>
</concept>