Gretyl's Portal

Heretto Help

Show Page Sections

Page Breaks

In Heretto PDF Generator, you can control page breaks and how elements are distributed over multiple pages. Follow information provided in this section to build PDF Generator publishing scenarios based on Gray and Color templates. For more information about the templates, see Gray and Color Templates.

Table 1. Styling used in the default Gray and Color templates
Resource location:@import url("https://jorsek.github.io/pdfgen.github.io/styles1.1/modules/layout/breaks.css");
Figure 1. Two Topics on One Page.

By default, if a topic can fit a page, it is distributed without any page breaks.

two topics on one page
Figure 2. Two Topics on Separate Pages.

By default, if a topic cannot fit a page, it is distributed on a separate page.

two topics on two pages
Figure 3. Definition List Broken over Multiple Pages.

By default, elements like definition list and paragraph are distributed over multiple pages with page breaks.

breaks definition list

Distribute Non-Chapter-Level Topics Without Page Breaks

You can avoid adding breaks between topics to save space. By default, if a topic fits a page, it is distributed without any page breaks.

  1. In the top-left corner, click the Main Menu and go to PDF Generator.
  2. In the PDF Generator scenarios screen, click the publishing scenario you want to edit.
  3. In the CSS tab, add this code.
    /* Break topics inside. */
    article {
        break-inside: auto;
    }
    /* Do not break chapter-level topics. */
    article:has(.topictitle1) {
        break-inside: avoid;
    }
  4. Click Save Scenario.
  5. Click the Select map to preview button to select the map you want to test with the updated scenario. Once selected, click the Generate PDF button.

Topics that are added below chapter-level are distributed without page breaks. This saves space in your publication.

Figure 4. Topics Distributed Without Page Breaks
topics distributed without page breaks

Decide Which Elements Should Be Broken Over Multiple Pages

You can decide which DITA elements are broken over multiple pages.

  1. In the top-left corner, click the Main Menu and go to PDF Generator.
  2. In the PDF Generator scenarios screen, click the publishing scenario you want to edit.
  3. In the CSS tab, add this code. You can customize the code by assigning the specific DITA elements to either break-inside: auto or break-inside: avoid.
    /* Break the following elements over multiple pages: */
    .table,
    .code,
    .entry,
    .xref,
    .sysoutput,
    .varname,
    .filepath,
    .userinput,
    .stepxmp,
    .stepresult,
    .info,
    .dd,
    .result {
      break-inside: auto;
    }
    
    /* Avoid breaking the following elements over multiple pages: */
    .note,
    .dt,
    .title,
    .codeph,
    .userinput,
    .sysoutput,
    .fig,
    .abstract,
    .shortdesc,
    .example,
    .context,
    .prereq
    .postreq {
      break-inside: avoid;
    }
  4. Click Save Scenario.
  5. Click the Select map to preview button to select the map you want to test with the updated scenario. Once selected, click the Generate PDF button.

DITA elements are broken or not broken over multiple pages according to what you defined in the CSS.

Prevent Breaking Definition Title and Definition Description Elements

You can prevent breaking the definition title and definition description elements over multiple pages. To do that, you need to modify both your CSS and XSLT code in a PDF Generator scenario.

  1. In the top-left corner, click the Main Menu and go to PDF Generator.
  2. In the PDF Generator scenarios screen, click the publishing scenario you want to edit.
  3. In the CSS tab, add this code:
    .dlentry {
      break-inside: avoid;
    }
  4. In the XSLT tab, add this code under the <xsl:import> tag(s):
    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
    
      <xsl:import href="/db/sdk2/internal/pdf_generator/pdf_generator.xsl"/>
    
    <!-- Add this code -->
      <!-- DL entry wrapper -->
      <xsl:template match="*[contains(@class, ' topic/dlentry ')]" name="topic.dlentry">
        <div class="dlentry">
          <xsl:apply-templates/>
        </div>
      </xsl:template>
    <!-- End of add this code -->
    
    </xsl:stylesheet>
  5. Click Save Scenario.
  6. Click the Select map to preview button to select the map you want to test with the updated scenario. Once selected, click the Generate PDF button.

In the definition lists, the titles and descriptions are not broken over multiple pages.

Outputclass Attributes for Page Breaks

You can assign outputclass attributes to the DITA elements inside the topics. This enables you to configure how the specific elements are broken.

You can learn how to assign outputclass attributes here: Outputclass Attributes for PDF Generator.

With outputclass attributes, you can make this change to individual maps or topics, regardless of what is defined in the publishing scenario.

Table 2. Outputclass Attributes for Page Breaks

PDF Generator Gray and Color templates are configured to respect these outputclass attributes by default. As a result, once you add them to a file, they are immediately applied to your output. There is no need to modify your PDF Generator scenario.

Outputclass AttributeDescription

Target DITA Element

break_before

Forces a break before an element

topic, element inside a topic

break_after

Forces a break after an element

topic, element inside a topic

break_avoid

Prevents breaking the element

element inside a topic

break_inside

Breaks the element over multiple pages

element inside a topic

break_topics

Distributes non-chapter-level topics one-by-one over multiple pages. The same as: Distribute Non-Chapter-Level Topics Without Page Breaks.

map