Split step

Splits input XHTML document, whether styled or semantic, into several pages and saves these pages to disk.

This step also generates a frameset and a table of contents used as the left frame of the frameset. While an obsolete HTML feature, a frameset makes it easy browsing the generated pages. Moreover the table of contents used as the left frame is a convenient way to programmatically list all the generated pages.

The result of the this step is the file containing the frameset.

For clarity, the “split.” parameter name prefix is omitted here.

However when you’ll pass any of the following parameters to w2x, please do not forget this prefix. Example: -p split.split-before-level 8.

Parameters:

Name

Value

Description

allow-lonely-heading

A boolean: true (same as: yes | on | 1) | false (same as: no | off | 0).

Default: false.

If specified as true, allow a page to contain just a heading and nothing else.

indent

A boolean: true (same as: yes | on | 1) | false (same as: no | off | 0).

Default: false.

Specifies whether the save files should be indented.

Note:

Do not specify indent=”true” in production.

The XML indentation created this way being very simple, this may add whitespace inside elements where space characters are significant.

out-file

A file path.

No default (required).

Specifies the path of the file containing the frameset. A relative file path is relative to the current working directory.

This step always generates several files, all in the same directory as file out-file.

This output directory is created on the fly if needed too. However, the output directory, if it already exists, is not automatically made empty.

The file specified by out-file contains the frameset. Let’s suppose out-file is temp\foo.html.

The table of contents of the frameset, its left frame, is created in temp\foo-TOC.html.

Unless parameter use-id-as-filename has been specified as true, the styled HTML pages are created in temp\foo-0.html, temp\foo-1.html, temp\foo-2.html, …, temp\foo-N.html.

split-before-level

Outline level between 0 (e.g. style “Heading 1”) and 8 (e.g. style “Heading 9”).

Default: 0 (split at “Heading 1”).

In order to generate multi-page styled HTML, that is, frameset, Web Help, EPUB, we need to automatically split the input XHTML document into pages.

A new page is created each time a paragraph having an outline level less than or equal to specified split-before-level parameter is found in the source.

An outline level is an integer between 0 (e.g. style “Heading 1”) and 8 (e.g. style “Heading 9”).

The default value of parameter split-before-level is 0, which means: for each “Heading 1”, create a new page starting with this “Heading 1”.

See also Important tip.

use-id-as-filename

A boolean: true (same as: yes | on | 1) | false (same as: no | off | 0).

Default: false.

By default, the save files of the generated pages have the same basename as out-file, except that a number is appended to this basename. Example: out-file is temp\foo.html; the save files of the generated pages are thus: temp\foo-0.html, temp\foo-1.html, temp\foo-2.html, …, temp\foo-N.html.

In a MS-Word document, a heading is often given a bookmark. The Convert step translates this bookmark to an ID. When use-id-as-filename is specified as true, the save file of a page is given a basename corresponding to the ID of the heading used to start this page. When this heading ID is missing, the Split step fallbacks to the default behavior.