Document Properties
Kbid27X542
Last Modified04-Aug-2020
Added to KB29-Apr-2016
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Intershop Documentation Tool Kit

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

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.

xml2html_t

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.

xml2pdf_t

The tool kit currently supports creating two types of PDF files: a standard screen version that is intended to be read on a computer screen, and a print version that is intended for creating hard copies of a document. The main difference between the screen and print version is that the print version contains extra blank pages at the end of chapters to even out the page count.

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.

The control files are called when creating the output.

ish_dockit

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.

ElementNote
bookroot element in book control file
articleroot element in article control file
chapterin book only
prefacein book intended for online help only
sect<#>

sections are supported up to level 4 (sect1, sect2, sect3, sect4), sect1 is root in a content chunk file (which is not valid individually)

indexin book intended for PDF only

<?hard-pagebreak?>

may be used to force page breaks between structuring elements (although it is explicitly not recommended)

title

allowed as child of book/article, chapter, sect1 ... sect4, figure

titleabbrevallowed as child of chapter and sect1 ... sect4, used to specify a short title in addition to title
subtitleallowed as child of book
parachild of sect<#>, tip, note, caution, listitem
tipchild of sect<#>, used to highlight informational notes
notechild of sect<#>, used to highlight notes
cautionchild of sect<#>, used to highlight warnings
programlisting

child of sect<#>, verbatim text, such as code fragments and examples

itemizedlist

child of sect<#>, mark="square" or mark="disc" ; if the mark attribute is missing the list is rendered as if mark="disc" was specified

orderedlistchild of sect<#>
listitemchild of itemizedlist, orderedlist
tablechild of sect<#>
captionchild of table (table title)
colgroupchild of table
col

child of colgroup, supports the width attribute with percentage values

theadchild of table (table header)
tbodychild of table (table body)
trchild of thead, tbody
thcell in a header row, child of tr within thead
tdcell in a body row, child of tr within tbody
figurechild of sect<#>, for figures on paragraph level
mediaobjectchild of figure
imageobjectchild of mediaoject
imagedata

child of imageobject, default attributes are width="100%" fileref="&image_path;/" format="PNG"

indextermchild of sect<#>, zone="" attribute
primarychild of indexterm
secondarychild of indexterm
xrefinline element, internal cross-reference, with linkend="" attribute
ulinkinline element, link to an external target (URL), with url="" attribute
computeroutputinline element, text to be printed with monospaced font
emphasisinline element, text to be printed in italics
inlinemediaobjectinline element, for figures within paragraphs
imageobjectchild of inlinemediaobject
imagedatachild of imageobject, default attributes are fileref="&image_path;/.png" align="left" valign="middle" contentdepth="1em"

4.3 Example Book Control File

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

Intershop DocBook book
<!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.

Intershop DocBook article
<!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.

Intershop DocBook content file
<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>

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets