Asciidoctor-pdf: Make page break before sections configurable

[mojavelinux]

Make the page break behavior before sections configurable via the theme. The theme should be able to dictate which headings trigger an automatic page break.

[mojavelinux]

Currently, page breaks occur before level-1 sections (chapters) when the doctype is book. However, they do not occur for level-0 sections (parts).

When the doctype is article, page breaks do not occur at all.

We'll need to think about how to express this.

[cascer1]

I would love to be able to specify in my theme where breaks should and shouldn't go. Something like:

page:
  heading-1:
    break:
      before: true
      after: false

[mojavelinux]

I'm aiming to make the theme as faithful to and familiar as CSS as possible. Therefore, I'd like to draw on the properties defined in the CSS page spec.

See https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Pages

So it might be something like:

heading:
  h1:
    page_break_after: always
    page_break_before: auto

One problem we have is with identifying terminology. Right now we use "heading" and "h1", but not "chapter". In AsciiDoc, an h2 isn't always a chapter and an h1 isn't always a part. So we'll probably need to add those keywords to compliment h1, h2, etc, which are the general "bridge heading" case.

[cascer1]

Hmm, that format does make more sense. Will it still be possible to define the breaking behavior of any heading type (h1, h2..) as well as things such as chapter and heading?

I use a tool that automatically generates an asciidoc based on another input and I can't modify it to use "header" or "chapter" tags, so I'd love to see both implemented.

[mojavelinux]

Yes, my suggestion is additive. My point is that there's no way to target chapters and parts just by heading level. These are inherent structures in AsciiDoc and we need to have a way to refer to them.

[Omnipresent]

If I have a asciidoc like this

== Section 1
Some text
== Section 2
Some text
== Section 3
Some text

Is there any way to add page break between each section so that each section starts on a new page in a PDF?

[jstrickler]

I can take this one!

The "<<<" directive at the beginning of a line adds a page feed. It can be
any length, but minimum is 3.

== Section 1
Some text

<<<

== Section 2

Some text

<<<

== Section 3
Some text

<<<

etc etc

On Tue, May 23, 2017 at 12:01 PM, Omnipresent [e-mail]
wrote:

If I have a asciidoc like this

== Section 1
Some text
== Section 2
Some text
== Section 3
Some text

Is there any way to add page break between each section so that each
section starts on a new page in a PDF?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/asciidoctor/asciidoctor-pdf/issues/74#issuecomment-303499307,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ADV0Ftgclxw2AANu-s2gEJeaGrUvoiREks5r8yzwgaJpZM4DHlTL
.

[Omnipresent]

Thanks!

[mojavelinux]

:+1:

[RazrFalcon]

Will be very useful.

[mojavelinux]

Currently, there are two page breaks. One before a part and one before a chapter. I think the simplest thing to do here is to be able to control them. Let's use the following two theme keys:

• heading_part_break_before
• heading_chapter_break_before

A value of "auto" will disable the forced break (letting it break naturally, if the end of the page has been reached). The default value is "always" (which essentially mean force).

Here's an example of how to disable the page break before chapters (but leave the one for parts):

heading:
  chapter_break_before: auto

Since the page break before a chapter can be configured, we should also allow the page break after a part to be configured (essentially the break between the part title / intro and chapter).

• heading_part_break_after

By default, this one will be auto. It can be set to always.

[mojavelinux]

Setting the before breaks to auto will disable the calls to start_new_chapter and start_new_part, respectively. The sole purpose of these methods is to create the page break, so they are only relevant when that's enabled.