Provided by: herold_8.0.1-1_all bug

NAME

       herold - HTML to DocBook converter

SYNOPSIS

       herold [OPTIONS]

DESCRIPTION

       The reuse of HTML content in presentation-neutral form is a frequent problem. One possible
       solution is to convert HTML to DocBook XML, because DocBook is a semantic markup language
       for documentation, which enables its users to create document content that captures the
       logical structure of the content.

       The command line tool herold can be used to convert HTML to DocBook. Because HTML elements
       are often used not as intended, the possibilities for such a transformation are somewhat
       limited. herold is part of the dbdoclet suite of tools. For more information visit
       http://www.dbdoclet.org.

OPTIONS

       --docbook-add-index, -x
           Automatically add an index element at the end of the document.

       --docbook-decompose-tables, -T
           Decomposes the tables from the HTML code into single paragraphs. This can be useful,
           if a document contains a lot of tables for formatting reasons.

       --docbook-encoding, -d
           Specifies the encoding of the generated DocBook XML files.

       --docbook-root-element, -r
           The root element of the document. Possible values are: book, article, reference, part,
           chapter or section. The default value for this option is 'article'

       --docbook-title, -t
           The title for the resulting document.

       --in, -i
           Specifies the HTML input file.

       --help, -h
           Prints a help page on the console.

       --html-encoding, -s
           Specifies the encoding of the HTML source files, such as ISO-8859-1.

       --out, -o
           Specifies the DocBook XML destination file.

       --profile, -p
           A profile file with predefined settings.

       --verbose, v
           Enables the verbosity for the console output.

       --version, -V
           Displays the version of herold.

CONFIGURATION

       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 /* my comment */ , single line comments look like // my comment\n.

   Mandatory Elements
       A profile for herold must start with the line transformation html2docbook;.

   Section HTML
       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.

   Section DocBook
       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.

   Section node
       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.

   Section attribute
       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";
           }

   Section section-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.

   Section list-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.

COPYRIGHT

       Copyright 2001-2015 Michael Fuchs. License GPLv3+: GNU GPL version 3 or later
       http://gnu.org/licenses/gpl.html. This is free software: you are free to change and
       redistribute it. There is NO WARRANTY, to the extent permitted by law.

AUTHOR

       Michael Fuchs
           Software Engineer