Hi, The long story:
Because Asciidoc is not a presentational markup, it does not actually do any of the "unbreakable" processing, the settings in Asciidoc source are just instructions for the toolchain, which for PDF is either Asciidoc-Python(3) or Asciidoctor producing docbook that is processed by dblatex or FOP, or Asciidoctor native (but still experimental) built in PDF generation. IIUC unbreakable applies to within an element eg a table, and keep together applies to more than one element eg a table and its caption. Page based layout is performed by: dblatex via the latex toolchain, FOP after XSLT processing, or the Asciidoctor-PDF backend itself. They decide page breaks based on a variety of criteria possibly including: settings for allowed sizes of widows and orphans, implicit and explicit breakable/unbreakable, implicit and explicit keep together, size of the element (if its bigger than a page you are gonna get a break in any case), the possibility to float text past tables and images and the settings to control that. The complexity of page break computation varies between backends, and most of those settings are backend specific. What their defaults are, where they are honoured and if they are honoured at all at this point depends on the backend. So your varying experience is likely due to the different capabilities and default settings of the PDF generators page layout engines. I havn't done a deep comparison of page layout approaches, but it is my understanding that Latex as used by the dblatex toolchain supports all the above criteria and settings, so perhaps you should try playing with the settings for that. However even the smartest page layout algorithm is only a machine, and as you pointed out it can be necessary to specify unbreakable explicitly and sometimes you need to manually force a break for human aesthetics reasons. The ifdef you found is the correct way of inserting a manual page break for PDF only. For settings that apply to individual elements like unbreakable, the Asciidoc way of passing those to the backends is attributes or (my preference) roles applied to the element. As you discovered (un)breakable was historically implemented as an attribute which means the Asciidoc processor needs to apply it, and as you found as a comment on Asciidoctor, keep-together has not been implemented. As an aside, as Asciidoctor said, keep-together should be a role, and unbreakable should also transition to a role since its the purpose of roles is as classifications for the backend to use for layout guidance and do not have to be implemented in the front end, so layout specific roles can be added more easily than attributes and many backends have configurability that allow user roles to control stuff the basic Asciidoc language doesn't know about. The short story: Automatic page layout is rule based and rules have limited aesthetic judgement so may insert page breaks in unsatisfying places. You may need to tweak the PDF backends settings and/or apply the unbreakable attribute and/or enforce breaks manually to override layout rules. But in all cases it depends on the layout engines capabilities and you may need to try several to find the best for your purposes. Cheers Lex On Tue, 28 Aug 2018 at 04:11, rdiezmail-buspirate via asciidoc <[email protected]> wrote: > > Hi there: > > I am evaluating AsciiDoc for my documentation needs. > > The one thing that bothers me most often with Microsoft Word or LibreOffice > Writer is that paragraphs or tables are not kept together when generating a > PDF or printing. Not everyone can always read the docs on a screen. It looks > unprofessional when a page break comes at the wrong time. > > I haven't learnt too much about AsciiDoc yet, but support for keeping > paragraphs together does not seem quite right yet. > > I found this on the Internet: "You can apply the unbreakable option globally > to all block elements by defining the unbreakable-option attribute in your > document header." > > But I could not find a practical example with paragraphs or with a table or > item list. > > I found this from tool AsciiDoctor: "I also want to mention that there's a > block role in AsciiDoc called "keep-together" that was designed to control > this sort of thing. We don't currently honor that role, but we could." > > I also saw this comment: > > "You said you tried the FOP backend, did you try using the dblatex > backend, it converts docbook to latex and therefore (theoretically) > can make use of that expertise." > > I also saw that Asciidoc-pdf does support some "keep-together" option, but > does not document exactly how to use it. > > There is also some way I found to manually trigger a page break for PDF > output only: > > Page break only in PDFs: ifdef::backend-pdf[<<<] > > > This is all rather vague and inconsistent (keep-together/unbreakable). > > Is there a clean way to mark some content as "keep together", so that it > works no matter what output format I want? > > The marketing and sales guys do not like bad-looking documentation. I must > say, abrupt page breaks do look unprofessional. It is a shame, but this > detail is serious enough that it currently prevents my switching to AsciiDoc. > > Thanks in advance, > rdiez > > -- > You received this message because you are subscribed to the Google Groups > "asciidoc" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/asciidoc. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/asciidoc. For more options, visit https://groups.google.com/d/optout.
