Re: [Firebird-docs] Widowed section headers in PDF

[Paul V. <pa...@vi...>]

Hi Philippe,

> on my linux machine, I use db2pdf for my technical doc, and I have
> page-break so it might be possible with FOP too ??

Yes, using page-break as such is no problem. The problem is: where to
insert it? Because you don't know where it's needed until the PDF is
produced and you find widowed headers. And you *only* want to place it
where it's needed or you'll get unwanted pagebreaks.

So (until FOP implements keep-with-next, or until we find a better
alternative) I guess the best solution is:

  repeat
    build the PDF;
    find first occurrence of a widowed header;
    if found, insert a pagebreak before that header;
  until no widowed headers remain.

This is not exactly elegant, but given the rate at which we publish
PDFs it's certainly feasible. After all, we only have to run this
cycle on the docs we publish; not on all the versions we build
in-between for ourselves or for comments by others.

Next question: how to insert the pagebreak? We don't have support for
a <?dbfo break...> instruction so we'd have to implement that first;
only then could we include such a PI in our docs.

This has two drawbacks:
- spending time to implement something that is essentially a hack;
- the pagebreaks will be in our XML sources; if the document is
  edited, chances are that some of them will have to be removed, but
  this could easily be forgotten. Even if not, I think it pollutes
  the source.

The better solution is therefore to insert the pagebreaks directly
into the .fo file. Open it in a text or XML editor, use the search
function to find the right spot, and change e.g.:

  <fo:block font-size="12pt" ...>Using a GUI client</fo:block>

to

  <fo:block break-before="page" font-size="12pt" ...>Using a GUI client</fo:block>

Of course it's still a hack, but now it takes less time and we keep
the sources clean.

So you run the cycle like this:

  "build pdf";
  repeat
    find first widowed header in PDF file;
    find that spot in the .fo and add break-before attribute;
    "build fo2pdf";
  until no more widows found.

BTW, the .fo is in manual/build/docs. As soon as you issue a "build
fo" or "build pdf", your manually inserted pagebreaks will be lost!

If someone has a PDF ready to publish but finds this too complicated,
I don't mind doing it myself.


> As far as the rationale for the DTD not providing an element to
> force pagebreaks in rendered output, it's just consistent with the
> fact that the DTD by design provides markup only for modeling
> structure and content, not presentation.

That's entirely correct; pagebreaks don't belong in the DocBook DTD.


Greetings,
Paul Vinkenoog