## 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. 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.