Global and/or per-section 'keep header with text' option

[castillar]

(Apologies if this is a duplicate--couldn't find anything that quite fit.)

It would be really good if AsciiDoc had a way to indicate that headers and their associated text should stick together across pages. As an example, if we had the following text:

---

== This is header1
This is header1's text

== This is header2
This is header2's text

---

If there were room on a page for header2 but not all of its associated text, then both the header and the text would be bumped to the next page. Right now, if there is room for the header and some text, AsciiDoctor will put the header and a line or two and then the rest on the next page, which is not always the desired outcome (in some formal documents, it's better to just put a page break and keep everything together monolithically).

There was a brief conversation about this on the AsciiDoc Google Group last summer (https://groups.google.com/forum/#!searchin/asciidoc/keep-together|sort:relevance/asciidoc/YNW4zAzwPWs/F6xviPefBAAJ); the upshot of that seemed to be that extending [options=unbreakable] to open blocks the way it is for things like tables would make this work, but there may be other ways to accomplish it.

[mojavelinux]

In which output format / converter do you intend for this information to be used? It's not relevant for HTML output since HTML output doesn't have pages. Do you mean for it to be propagated to the DocBook output?

[mojavelinux]

AsciiDoctor will put the header and a line or two and then the rest on the next page, which is not always the desired outcome

In which output?

[castillar]

Sorry, mea culpa: I should have been more specific. This is with asciidoctor-pdf, pushing content into PDFs. You're right: page breaks make no sense in an HTML context; I was thinking about print context like the PDF or DocBook output.

[u0421793]

From my print publishing background (where we refer to this as 'keeps and breaks'), a widely acceptable default is two lines. That is, two or more lines of body copy may accompany a heading at the end of a page (and similarly, two or more lines of overmatter may fall onto the top of the following page), but not less than this. Nobody wants just one line at either end. Three is a nicer visual outcome, but in practice, it not only makes it a lot more difficult to occur at all, when it does, it leaves a more problematic gap than is comfortable. Anything outside of a default keeps&breaks value of two is either a special case, or house style, or some amateur fiddling around with the numbers to see what they do.

[mojavelinux]

This is a duplicate of asciidoctor/asciidoctor-pdf#38. Let's continue the discussion there.