- Menu
- Sitemap
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.
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.
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.
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.
| Element | Note |
|---|---|
| book | root element in book control file |
| article | root element in article control file |
| chapter | in book only |
| preface | in 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) |
| index | in 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 |
| titleabbrev | allowed as child of chapter and sect1 ... sect4, used to specify a short title in addition to title |
| subtitle | allowed as child of book |
| para | child of sect<#>, tip, note, caution, listitem |
| tip | child of sect<#>, used to highlight informational notes |
| note | child of sect<#>, used to highlight notes |
| caution | child of sect<#>, used to highlight warnings |
| programlisting | child of sect<#>, verbatim text, such as code fragments and examples |
| itemizedlist | child of sect<#>, |
| orderedlist | child of sect<#> |
| listitem | child of itemizedlist, orderedlist |
| table | child of sect<#> |
| caption | child of table (table title) |
| colgroup | child of table |
| col | child of colgroup, supports the |
| thead | child of table (table header) |
| tbody | child of table (table body) |
| tr | child of thead, tbody |
| th | cell in a header row, child of tr within thead |
| td | cell in a body row, child of tr within tbody |
| figure | child of sect<#>, for figures on paragraph level |
| mediaobject | child of figure |
| imageobject | child of mediaoject |
| imagedata | child of imageobject, default attributes are |
| indexterm | child of sect<#>, zone="" attribute |
| primary | child of indexterm |
| secondary | child of indexterm |
| xref | inline element, internal cross-reference, with linkend="" attribute |
| ulink | inline element, link to an external target (URL), with url="" attribute |
| computeroutput | inline element, text to be printed with monospaced font |
| emphasis | inline element, text to be printed in italics |
| inlinemediaobject | inline element, for figures within paragraphs |
| imageobject | child of inlinemediaobject |
| imagedata | child 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.
<!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>
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.
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.
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.
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.
| Element | Note |
|---|---|
| book | root element in book control file |
| article | root element in article control file |
| chapter | in book only |
| preface | in 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) |
| index | in 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 |
| titleabbrev | allowed as child of chapter and sect1 ... sect4, used to specify a short title in addition to title |
| subtitle | allowed as child of book |
| para | child of sect<#>, tip, note, caution, listitem |
| tip | child of sect<#>, used to highlight informational notes |
| note | child of sect<#>, used to highlight notes |
| caution | child of sect<#>, used to highlight warnings |
| programlisting | child of sect<#>, verbatim text, such as code fragments and examples |
| itemizedlist | child of sect<#>, |
| orderedlist | child of sect<#> |
| listitem | child of itemizedlist, orderedlist |
| table | child of sect<#> |
| caption | child of table (table title) |
| colgroup | child of table |
| col | child of colgroup, supports the |
| thead | child of table (table header) |
| tbody | child of table (table body) |
| tr | child of thead, tbody |
| th | cell in a header row, child of tr within thead |
| td | cell in a body row, child of tr within tbody |
| figure | child of sect<#>, for figures on paragraph level |
| mediaobject | child of figure |
| imageobject | child of mediaoject |
| imagedata | child of imageobject, default attributes are |
| indexterm | child of sect<#>, zone="" attribute |
| primary | child of indexterm |
| secondary | child of indexterm |
| xref | inline element, internal cross-reference, with linkend="" attribute |
| ulink | inline element, link to an external target (URL), with url="" attribute |
| computeroutput | inline element, text to be printed with monospaced font |
| emphasis | inline element, text to be printed in italics |
| inlinemediaobject | inline element, for figures within paragraphs |
| imageobject | child of inlinemediaobject |
| imagedata | child 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.
<!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>
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.