1 Introduction

This document introduces the Intershop Documentation Tool Kit, a software tool kit for creating end user documentation (online help, books) for the management tools of Intershop products. This document is targeted at consultants or partners who intend to modify Intershop's default end user documentation.

The Intershop Documentation Tool Kit (DocKit) can transform DocBook XML documents into various output formats. Currently, there is out-of-the-box support for HTML and PDF based on DocBook DTDs and some XSL stylesheets, using Saxon and Apache FOP. So you should be familiar with authoring XML documents and using XSLT processing.

For information about using the tool kit, refer to Cookbook - Intershop Documentation Tool Kit.

2 DocKit Tools and Components

The Intershop Documentation Tool Kit includes the following tools and components:

• Convenience scripts to facilitate the transformation process. These scripts are located in the tool kit's root directory and are available as shell scripts (for Linux and Mac OS X) and batch scripts (for Windows):

  • init.sh|bat, initializes the shell environment

  • val.sh, checks a DocBook XML source document for well-formedness and validates it against its DTD (Linux and Mac OS X only)

  • html.sh|bat, transforms DocBook into HTML output

  • pdf.sh|bat, transforms DocBook into PDF output

  • join.sh|bat, merges DocBook XML sources distributed over multiple files into a single XML file

  • convert.sh, transforms legacy Intershop documents from DocBook v4.2 into DocBook v4.5 (Linux and Mac OS X only)

• Java based tools, required for the transformation (to be downloaded separately, see Recipe: Setting Up Intershop Documentation Tool Kit)

  • Saxon-B 9.1.0.8, an XSLT Processor for transforming XML, published under the Mozilla Public License v1.0

  • Apache FOP 1.0, a Formatting Objects Processor for rendering PDFs from XSL-FO, published under the Apache License v2.0

  • Apache XML Commons Resolver 1.2, an XML entity and URI resolver for resolving DTD locations, published under the Apache License v2.0

• XSL stylesheets and customizations

  • Intershop XSLT Stylesheets for creating HTML output

  • DocBook XSL stylesheet v1.75.2, the standard DocBook stylesheets, "plain" open source, see http://wiki.docbook.org/DocBookLicense

  • Customization layer for the FO part of the standard DocBook stylesheets, including the fonts to be used when generating PDF output

  • XSLT stylesheet used by convert.sh for upgrading legacy Intershop documents

• DocBook DTD
  

  • DocBook XML DTD v4.5

The Intershop Documentation Tool Kit has run successfully on:

• (X)Ubuntu 12.04, 14.04, 16.04
• Windows 7, Windows 8.1, Windows 10
• MacOS X 10.6.8

3 Document Generation Basics

3.1 HTML Output

For transforming XML source documents to HTML output, the Intershop Documentation Tool Kit provides the script html.sh|bat, and XSL-T stylesheets residing in <ish_docukit>/xsl/custom-xsl/html.

The following diagram illustrates the transformation process.

The html.sh|bat script uses the Saxon XSLT processor (included in the tool kit) for the transformation process.

3.2 PDF Output

For transforming XML source documents to PDF output, the Intershop Documentation Tool Kit provides the script pdf.sh|bat, and customizations (customization layer) to the standard DocBook XSL stylesheets. All files comprising the FO customization layer reside in <ish_docukit>/xsl/custom-xsl/fo.

The customization layer includes the following:

• XSL-FO stylesheets overwriting the default DocBook stylesheets
• Customized FOP configuration
• Custom fonts
• Image files with corporate logo

The following diagram illustrates the transformation process.

4 Source Documents Structure

4.1 Content Distribution

Typically, Intershop distributes the documentation content across multiple source files. These content chunk files are then combined using a control file, which first declares the multiple source files as entities and then includes them in the intended order. This approach has two major benefits:

• It allows for the distributed development of different parts of a document.
• It allows for complex documents that are composed of flexible and reusable parts.

4.2 Supported Elements

Generally, the DocBook definition includes structuring elements (used to structure documents), block elements (to actually hold content) and inline elements (to hold specific content within block elements). The following table lists the elements supported by the Intershop Documentation Tool Kit.

4.3 Example Book Control File

The following listing illustrates the typical structure of a book control file, which includes two content files.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    <!ENTITY image_path "images">
    ...
    <!ENTITY intro SYSTEM "intro.xml">
    <!ENTITY doing SYSTEM "doing.xml">
    ...
]>
<book>
    <title>...</title>
    <bookinfo>
    ...
    </bookinfo>
    <chapter id="about">
        <title>About ...</title>
            &intro;
            ...
    </chapter>
    <chapter id="working">
        <title>Working With ...</title>
            &doing;
            ...
    </chapter>
    ...
    <index/>
</book>

4.4 Example Article Control File

The following listing illustrates the typical structure of an article control file, which includes two content files.

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    <!ENTITY image_path "images">
    ...
    <!ENTITY intro SYSTEM "intro.xml">
    <!ENTITY doing SYSTEM "doing.xml">
    ...
]>
<article>
    <title>...</title>
    <articleinfo>
    ...
    </articleinfo>
    &intro;
    ...
    &doing;
    ...
</article>

4.5 Example Content File

The following listing illustrates the element usage in the content files. Use this listing as a reference for allowed elements, allowed element nesting, structures etc.

<sect1 id="">
    <title></title>
    <titleabbrev></titleabbrev>
    <indexterm zone="">
        <primary></primary>
        <secondary></secondary>
    </indexterm>
    <para></para>
    <para><xref linkend=""/></para>
    <para><ulink url=""></ulink></para>
    <para><computeroutput></computeroutput></para>
    <para><emphasis></emphasis></para>
    <tip>
        <para></para>
    </tip>
    <note>
        <para></para>
    </note>
    <caution>
        <para></para>
    </caution>
    <sect2 id="">
        <title></title>
        <para></para>
        <sect3 id="">
            <title></title>
            <para></para>
            <sect4 id="">
                <title></title>
                <para></para>
            </sect4>
        </sect3>
        <para><inlinemediaobject><imageobject><imagedata fileref="&image_path;/.png" align="left" contentdepth="1em"/></imageobject></inlinemediaobject></para>
        <figure>
            <title></title>
            <mediaobject>
                <imageobject>
                    <imagedata width="100%" fileref="&image_path;/" format="PNG"/>
                </imageobject>
            </mediaobject>
        </figure>
        <table>
            <caption></caption>
            <colgroup>
                <col width="30%"/>
                <col width="70%"/>
            </colgroup>
            <thead>
                <tr>
                    <th></th>
                    <th></th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td></td>
                    <td></td>
                </tr>
                <tr>
                    <td></td>
                    <td></td>
                </tr>
                <tr>
                    <td></td>
                    <td></td>
                </tr>
            </tbody>
        </table>
        <orderedlist>
            <listitem>
                <para></para>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
                <para></para>
            </listitem>
        </orderedlist>
        <itemizedlist mark="square">
            <listitem>
                <para></para>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
                <para></para>
            </listitem>
        </itemizedlist>
        <itemizedlist mark="disc">
            <listitem>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
            </listitem>
            <listitem>
                <para></para>
            </listitem>
        </itemizedlist>
        <programlisting></programlisting>
    </sect2>
</sect1>