Importing an existing looseleaf document

A manual leaf split allows you to import an existing looseleaf document into a TopLeaf partition declared with a partition based numbering scheme. Leaf boundary markers within the document identify the content allocated to an initial set of published leaves. After importing the document, TopLeaf automatically moves the partition to the published phase.

Procedure

To import an existing set of leaf boundaries you must:

  1. Insert one or more leaf boundary markers into your document content;

  2. Assign a default, or leaf specific release labels to the leaves in the initial leaf set;

  3. Perform a Leaf split;

  4. Create the Next Update release;

  5. Compose the partition;

  6. Verify the initial set of published pages.

Identifying existing leaf boundaries

Leaf boundaries within an imported looseleaf publication are identified using boundary marker processing instructions. Each initial leaf boundary marker defines:

  • the point at which the content of one leaf ends and the content of the next leaf begins;

  • an optional leaf folio that identifies the leaf;

  • an optional release label for the leaf;

  • if the boundary is located after a hyphenated or non-hyphenated word break;

  • if the boundary is located within a paragraph, or after a paragraph break.

The format of an initial leaf boundary marker is:

<?TL properties ?>

The properties of each initial leaf boundary are defined using the following pseudo-attributes:

Atttribute Type Meaning
folio string

The folio is a valid TopLeaf leaf folio consisting of a primary folio index and up to four additional point page levels (for example, 1, 1.1, or 123.1.1). The folio must conform to the page folio format defined for the partition.

Folios that identify leaf boundaries for point pages must use a common folio level separator character. The publication style sheet must define the same folio separator character — please refer to the <leaf-settings/> directive for more details.

By default, the initial folio for a partition is assumed to be the page number declared in the First Folio indicator. If you do not specify a folio, TopLeaf will assign the leaf content to the next available folio.

relstr string

If defined, the value specifies a release label for the leaf. After the mainwork is leaf split, TopLeaf will associate the leaf with the specified release label until the leaf content is changed in a subsequent release.

[Note] Note

TopLeaf does not apply any normalization rules to the release label value. It is the user’s responsibility to ensure that the specified release labels are consistent and valid.

hyphen number

If defined, and non-zero, specifies a hyphenation word break within a paragraph at which the leaf boundary occurs.

When the mainwork is leaf split, TopLeaf will position the leaf break within the word. When the leaf is rendered in the first update, TopLeaf will automatically justify the last line within the leaf and insert a hyphen at the end of that line. TopLeaf will apply the current font and paragraph style to the content that continues on the following leaf.

It is the user's responsibility to ensure that the word break is a valid hyphenation point.

wrdbrk number

If defined, and non-zero, specifies a word break point at which the leaf boundary occurs.

It is sufficient to declare wrdbrk as a non-zero value to mark the position of a word break within a word. TopLeaf will automatically calculate the effective position of the word break offset when the leaf split is applied.

When the mainwork is leaf split, TopLeaf will position the leaf break within the word. When the leaf is rendered in the first update, TopLeaf will automatically justify the last line within the leaf then apply the current font and paragraph style to the content that continues on the following leaf.

block number

If defined and non-zero, specifies that the leaf boundary marker coincides with a paragraph boundary. If defined and zero, specifies that the leaf boundary marker is positioned within a paragraph.

If the leaf boundary is positioned within a paragraph, then when the leaf is rendered in the first update, TopLeaf will automatically justify the last line within the leaf then apply the current font and paragraph style to the content that continues on the following leaf.

By default, TopLeaf assumes that a leaf boundary coincides with a paragraph boundary unless it is declared immediately after a space (U+0020) character, in which case the boundary is assumed to be positioned within a paragraph. An explicit block declaration can be used to override this behaviour.

The options hyphen, wrdbrk, and block are mutually exclusive.

In most cases, you will only need to specify the leaf folio and whether or not the leaf boundary is positioned after a hyphenated or non-hyphenated word break, as in the following example:

… assumes that any docu<?TL folio="7" hyphen="1" ?>ment presented to it …

When an existing leaf boundary is positioned after an inline word break or hyphenation point, the justification of the last line before the leaf boundary may cause it to be rendered with excessive interword spacing. The TopLeaf composition engine will automatically align the last line of a leaf to the left margin if the spaces between words in that line are stretched beyond a maximum threshold.

Positioning leaf boundaries

A leaf boundary marker declared at the beginning of a structural block must be positioned immediately before all adjacent start tags. Leaf boundaries that fall at the end of a structural block must be positioned immediately after all adjacent end tags. For example, if a leaf begins with the first item of an itemized list, position the leaf boundary marker before the itemized list:

Leaf specific release labels

The partition release label declares a default release label for each leaf in the mainwork. You can override this value by declaring a leaf specific release label within any initial leaf boundary marker. The following example declares a leaf specific release label for leaf 5 :

After the mainwork is leaf split, TopLeaf associates the initial leaves with the specified release label until the leaf content is changed in a subsequent release. When the content is typeset, a stylesheet Header or Footer mapping can use the {release-label} variable to reference the release label assigned to each leaf.

[Note] Note

The release number of the first update created after a manual leaf split is equal to the number of unique release labels declared for the initial leaf set.

Creating an initial set of published pages

A manual leaf split allocates the content of a mainwork to one or more leaves and then publishes the initial leaf set. It does not render the content of those leaves. To render an initial set of published pages you must create a new update and then compose that release. TopLeaf will create a single pair of output pages for each leaf declared by the manual leaf split.

It may not always be possible to construct TopLeaf style sheet rules that produce output that is identical to your existing published pages. In some circumstances, the content of a leaf cannot be rendered within a single pair of output pages. When this occurs, TopLeaf will overflow the excess content into one or more additional leaves that are not defined in the initial leaf set. The output pages associated with these additional leaves will not be included in the initial set of published pages unless you change or manually include the leaves that have overflowed.

In the following example, a manual leaf split creates an initial set of leaves 1, 3, 5 through to leaf 17. When the first update release is typeset, TopLeaf creates a baseline set of published pages for the initial leaf set. The composition log indicates that TopLeaf has created unexpected overflow leaves — the first of these is leaf 2a, created when rendering the content of leaf 1. TopLeaf will store a single pair of output pages for leaf 1 in the published page set, but the output pages for the overflow leaf 2a will only be included if you change or manually include the content of leaf 1.

The composition log file includes a summary list of any leaves that generate an overflow and cannot be rendered within a single pair of output pages:

[Note] Note

When you compose the first release after a manual leaf split, unexpected overflow leaves are listed as a messages in the typesetting log file. If you want TopLeaf to generate a warning when unexpected overflow leaves are created, include the command <leaf-settings warn-leafoverflow="yes" /> within the $document stylesheet mapping.

If you need to create a full reprint or PDF from a manually leaf split document, you must verify that TopLeaf has rendered the content of each initial leaf within a single pair of output pages, and manually included any leaves that generate an unexpected overflow. You do not need to perform this step if you intend to use the imported publication to create update packs that only contain new or modified leaves.

Restrictions

You should be aware of the following:

  • A manual leaf split can only be applied to a full looseleaf partition that uses a partition based numbering scheme.

  • All leaf folios must conform to the partition page folio format.

  • Leaf boundaries can only be positioned within content that is rendered within a data block.

  • Leaf boundaries cannot be positioned within a split table row or within a split column footnote.

  • A leaf boundary can only be declared if it has a precise corresponding location in the source document content. This means that there are some situations — for example, when a leaf boundary falls in the middle of an auto-generated disclaimer or table of contents — where a leaf boundary cannot be declared.

  • The restrictions on the positioning of leaf boundaries within scanned content also apply to initial leaf boundaries.

  • It may not be possible to construct TopLeaf style sheet rules that produce output that is identical to your existing published pages. In some circumstances, hyphenation and page ends will be different. This is not a problem if the TopLeaf output can be guaranteed to take less space.

  • Style sheet rules or content that force automatic leaf inclusions can result in the repositioning of leaf boundaries when the content is typeset and published.