Publishing XHTML output as a frameset

By default, the Toolkit produces XHTML output in which the index.html page is a hierarchical list of document contents. When you click on a linked topic in the list, your browser opens a new page.

If you have a document of any size, it may be more user-friendly to create an XHTML document using framesets, in which the hierarchical contents are on the left, and the displayed topic is on the right. The following figure shows an example.

With a few customizations to your DITA project, the Toolkit will produce frameset-based XHTML output automatically.

  1. Put an XHTML file called index.html into a directory accessible by the Toolkit (ours is in a project directory called build_files). The file should look similar to the following.
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></meta>
    <title>DITA Open Toolkit User Guide</title>
    <!-- The following two lines cause the default styling for the navigation frame
    to be the same as the content frame. -->
    <link href="CSS/commonltr.css" type="text/css" rel="stylesheet" />
    <link href="CSS/DITAOTUG_CSS.css" type="text/css" rel="stylesheet" />
    <!-- The left-hand navigation frame is 30% of the available space -->
    <!-- The right-hand content frame takes up the rest of the available space -->
    <frameset cols="30%,*">
    <!-- tocwin is the navigation frame -->
    <frame name="tocwin"     src="toc.html"></frame>
    <!-- contentwin is the content frame -->
    <frame name="contentwin" src="DITAOTUG_bkinfo.html"></frame>

    The frame called "tocwin" is the left-hand frame for your table of contents. The source (src) file is toc.html.

    The frame called "contentwin" is the right-hand frame for your content pages. The source (src) file, DITAOTUG_bkinfo.html in this case, is the first page displayed in the content frame. For the DITA Open Toolkit User Guide (this document), it is the title page.

    The TOC frame will take up 30% of the available space in the browser window, and the content frame will take up the rest.

  2. Add code to your Ant script similar to the highlighted examples in the following figure
    <!-- Create xhtml output -->
    <target name="dita2xhtml">
    <ant antfile="${toolkit_dir}${file.separator}conductor.xml" target="init">
    <property name="args.input" value="${projdir}/${MAP_file}"/>
    <property name="output.dir" value="${outdir}/xhtml"/>
    <property name="dita.temp.dir" value="${outdir}/temp"/>
    <property name="transtype" value="xhtml"/>
    <property name="args.draft" value="yes"/>
    <property name="args.indexshow" value="no"/>
    <property name="args.css" value="${projdir}/css_files/DITAOTUG_CSS.css"/>
    <property name="args.csspath" value="CSS"/>
    <property name="args.copycss" value="yes"/>
    <!-- Make the "index" file be toc.html -->
    <property name="args.xhtml.toc" value="toc"/>
    <property name="dita.extname" value="${EXTNAME}"/>
    <property name="dita.input.valfile" value="${ditaval_nonpdf}"/>
    <!-- Copy index.html to the output directory -->
    <copy todir="${outdir}/xhtml">
    <fileset dir="${projdir}/build_files"/>

    In the above code, the "args.xhtml.toc" parameter directs the Toolkit to substitute toc.html for the default index.html "index" page.

    The above code also directs the Toolkit to copy the index.html file in the build_files directory to the output directory in a postprocessing step.

Because the TOC for this document is so long, we have customized the XHTML output to use framesets as described above.