The details of a transformation are controlled by a profile file. A profile file offers more
possibilities to influence the transformation than the command line arguments. The following example
shows a typical profile file.
transformation html2docbook;
section section-detection {
attribute-class = ["^MsoHeading(\d+)$"];
section-numbering-pattern = "((\d+\.)+)?\d*\.?\p{Z}*";
}
section list-detection {
itemized-attribute-class = ["^MsoListBullet(\w*)$", "Aufzhlung(\w+)$];
itemized-strip-prefix = [ "-", "o", "\u00b7" ];
ordered-attribute-class = ["^MsoListNumbered(\w*)$"];
ordered-strip-prefix = [ "\d+\.\s+" ];
}
section HTML {
encoding = "windows-1252";
exclude = [ "//p[starts-with(@class, 'MsoToc')]", "" ];
}
section DocBook {
abstract = """<title>Lorem ipsum</title>
<para>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.sed, dolor
amet.</para>""";
add-index = true;
author-email = "me@somewhere.de";
author-firstname = "Michael";
author-surname = "Fuchs";
chunk-elements = [ "chapter", "section", "appendix" ];
// Syntax: chunk-<CHUNK-ELEMENT>-depth = <INT>;
chunk-section-depth = 3;
collapse-protected-space = "true";
copyright-holder = "Ingenieurbüro Michael Fuchs";
copyright-year = "2015";
corporation = "";
create-condition-attribute = false;
create-prolog = true;
create-remap-attribute = false;
create-xref-label = false;
decompose-tables = false;
detect-trapped-br = true;
documentation-id = "doc01";
document-element = "book";
encoding = "UTF-8";
hyphenation-char = "soft-hyphen";
image-data-formats = [ "gif", "base64" ];
image-path = "./figures";
language = "de";
release-info = "Version 3.1";
table-style = "all";
title = "Tutorial";
title-normalize-space = true;
use-absolute-image-path = false;
}
Syntax
A profile file consists mainly of sections. Sections are used to group parameters which share the same
context. Every section must start with the keyword section followed by the name of the section. After the
name comes the block of parameters, which is surrounded by curly braces. Parameters can be of type
String, Number, Boolean or Array. Strings must be framed with double quotes. If the String contains
newlines, use three double quotes instead of one. Arrays are framed with square brackets. Inside an
array, the elements must be comma separated. Every assignment must be finished by a semicolon. Multi line
comments have the form /*mycomment*/ , single line comments look like //mycomment\n.
MandatoryElements
A profile for herold must start with the line transformation html2docbook;.
SectionHTML
The section HTML defines parameters, which control the loading and parsing of the HTML input data.
encoding
The character set used to read the input stream.
exclude
Defines an array of xpath expressions. All matches are removed from the HTML DOM tree before
transformation.
SectionDocBook
abstract
The text for the abstract element of the info section. If the text is structured with newlines, use
three double quotes as delimiters. If the text starts with a "<" character, it is embedded into an
abstract element, otherwise the text is embedded into an para element inside of an abstract element.
The text will parsed and can contain DocBook elements.
add-index
If set to true, an index element is inserted at the end of the DocBook XML.
author-email
The email address of the author. If this parameter is set, it is used to create an info section at
the beginning of the document.
author-firstname
The firstname of the author. If this parameter is set, it is used to create an info section at the
beginning of the document.
author-surname
The surname of the author. If this parameter is set, it is used to create an info section at the
beginning of the document.
chunk-elements
Defines an array of element names. If an element of this list is detected while writing the output,
the element and all child nodes will be written to a separate file. This new file will be included
into the parent file with an xi:include tag. Recursive structures result in recursive includes. You
might want to use this, if you are transforming big HTML files and the resulting DocBook XML file
becomes uncomfortable large.
chunk-<CHUNK-ELEMENT>-depth
Defines the depth for a chunk element, until the chunking should be executed, eg chunk-section-depth
= 3. If an element defined for chunking is nested recursivley, you might want to control the depth to
which the chunking should be done. The default depth is 1, which means only the topmost element is
separated.
create-xref-label
if set to false, anchor elements doesn't get a xreflabel attribute.
decompose-tables
If set to true, tables structures will be ignored. The content of the table cells will be inserted
into the DocBook XML as a sequence of paragraphs. This parameter can be useful if your HTML contains
tables for formatting purposes. Normally you want to get rid of them, because they tamper the logical
structure.
document-element
The document element you want to use. Must be one of article, book, part or reference.
encoding
The character set which will be used for writing the output file.
image-data-formats
An array of image formats. These formats will be inserted as imageobject elements, additionally to
the format found in the src attribute of the corresponding img element. The original format is
inserted twice with the roles "html" and "fo". The other formats are inserted as "html-<FORMAT>" and
"fo-<FORMAT>".
title
The title of the resulting document. If this parameter is undefined, herold tries to dected the title
from the head section of the HTML data.
use-absolute-image-path
If you want absolute image paths in the fileref attribute of the imagedata element, set this
parameter to true.
Sectionnode
The mapping of HTML elements to DocBook element can be fine tuned by using node sections. If you have
HTML code which looks like the following fragment:
<ol class="procedure">
<li>Step 1</li>
<li>Step 2</li>
<li>Step 3</li>
</ol>
The resulting DocBook XML after the transformation would normally look like:
<orderedlist>
<listitem>Step 1</listitem>
<listitem>Step 2</listitem>
<listitem>Step 3</listitem>
</orderlist>
But what you would like to have is something like:
<procedure>
<step>Step 1</step>
<step>Step 2</step>
<step>Step 3</step>
</procedure>
To achieve this, you can use the following rules in our profile:
node "//ol[@class='procedure']" {
map-to = "procedure";
}
node "//ol[@class='procedure']/li" {
map-to = "step";
}
After the keyword node follows a xpath expression which is matched against the document element of the
HTML file (typically <html>). The parameter map-to defines the DocBook element, which is used instead of
the default mapping element.
Sectionattribute
An attribute section is more or less the same as a node section. Instead of redefining the mapping of a
HTML element to a DocBook element, the mapping for an attribute is changed. The following section maps an
attribute class='procedure' to role='procedure'.
attribute "//@class[contains(., 'procedure')]" {
map-to = "role";
}
Sectionsection-detection
The section section-detection is used to detect section elements in HTML code and to strip off any
numbering prefix from the titles.
Many authoring tools allow deeply nested sections. While exporting HTML, it happens, that the nesting
becomes deeper than six levels. HTML provides header elements for up to six levels, h1-h6, but no h7 or
even more. At this point, the formatting is normally done with the help of CSS and div or p elements.
herold is able to detect the header element of HTML, but it can not know about the export format of a
specific tool. To solve this problem even for some cases, you can specify the parameter attribute-class.
It consists of a list of regular expressions, which are matched against the class attribute of each HTML
element. If a match is found, the element is considered as a section element. The regular expression can
have group, which is interpreted as level indicator. The group must be the first group and it must match
against a number, e.g. ^heading(\d+)$. If the level can not be detected, a level of seven is assumed.
Because DocBook XSL stylesheets take care of the section numbering while transforming the DocBook XML to
a specific output, it is often necessary to strip the numbering already defined in the HTML page.
Otherwise you end up with two numbering texts in front of your titles. To help herold with the detection
of numbering patterns, use the parameter section-numbering-pattern.
attribute-class
A regular expression, which is applied to every p and div element. If the expression matches, the
current element is handled as a section element. If the regular expression has groups, the first
group will be used as nesting level, otherwise level seven is assumed.
section-numbering-pattern
Normally you want to get rid of the section numbering that comes with the HTML data, because it
becomes part of the title text in DocBook. The section numbers will the appear twice in your target
media. One from HTML and one from the DocBook XSL processing. The parameter section-numbering-pattern
defines a regular expression, which is matched against the beginning of every section title. If it
matches, the matching part is removed.
Sectionlist-detection
Sometimes lists are not represented with ul, ol or dl tags, but they are represented as p tags with
additional css formatting. If you use a tool, which creates or exports HTML with such a construct, the
conversion will end up with para elements, instead of the corresponding list elements in DocBook. To
recreate the lists in some cases, you can use the section list-detection. The parameters
itemized-attribute-class and ordered-attribute-class let you define lists of regular expression, which
should match against the class attribute of listitem elements in the HTML. herold tries to rebuild the
proper list structure from this information, even for nested lists.
Install Now
PNG Icons
