PDF2: Page sequence logic

I’d like to take a step back and describe some of the issues with PDFs and book publishing. Hopefully, by having a debate at this level, it will inform some of the decisions and requirements for PDF2.

TLDR: See summary at end. Cats Reading Books.

Equipment manufacturers have a large number of regulations and safety requirements to consider. These increase in severity from domestic equipment, to industrial to medical equipment. This often leads the manufacturer to print a booklet and include it with the equipment. The rationale is that the customer is more likely to read a printed booklet than they are to look at embedded documentation or an online resource.

Apple is a good example. Whilst they are known for minimalist documentation, they usually include a densely printed booklet with all the regulatory and safety requirements that the product meets, for multiple territories. Does anyone read this? The regulators certainly do, and so the primary aim is to avoid litigation.

The issue with printed technical documentation is that the print run is limited to the demand for the product. Apple doesn’t have an issue with this, of course, but many equipment manufacturers produce equipment in much smaller quantities. This leads to low print runs, and often short run digital print. It also affects the binding, and printed documentation is often in plastic spiral binding, or wire, calendar style binding, or even hole punched and put in ring binders. Medical equipment might include a book shelf worth of ring bound documentation.

So, what are the requirements for PDF and print?

Firstly, both ditamap and bookmap are equally valid and useful. Ditamap is great for a small safety or how to booklet. Bookmap handles the requirements for larger tomes.

Usually, the start of a new section is on a fresh page. By section this would be a chapter, ToC, appendix, etc. in a bookmap, or a top level topic in a ditamap. Top level implies the top level in a ToC, which would be the root of a ditamap, and a first level heading. Section in this context is not a DITA < section/>.

If the book is printed, then the start of each section would be on an odd page, and it would have facing pages, $mirror-page-margins = true(). This is pretty much ubiquitous, and applies equally to ditamap and to bookmap. By contrast, a PDF as an online or embedded resource might not require facing pages. A bookmap is almost certain to use facing pages because of its formality, whether it is actually printed or not.

The start of a section would typically include the section title, and perhaps the chapter number for a bookmap. As this information might also be in the page heading, the page heading is often removed from the first page of a section. This leads to a possible requirement for a different first page design. However, this is not always the case.

The requirement for a last page is quite different to that for a first page. There is no requirement for first page, last page design symmetry. The requirement for a last page is to do with pagination. If the book uses facing pages, then a situation can often arise where one section ends on an odd page, and the next has to start on an odd page. So the requirement, in this situation, is for the addition of a blank even page between the two sections.

Usually, a last blank page will use the even page design. However, with loose binding, a customer might enquire whether the page should be blank, or whether some information is missing. In this situation, a company might include a statement such as this in the heading: “This page is intentionally blank”. This is typically the only requirement for a last blank page design. If there is such a requirement, then this design could typically be used for every section type: chapter, appendix, ToC, index, etc.

TLDR: So a lot rests on the choice of facing pages or not, $mirror-page-margins.

Without facing pages:

Only a single page design, not odd and even page designs. If there is a first page requirement, this could be an odd or even page. The last blank page pagination situation never arises, by definition. Therefore, no last page requirement.

With facing pages:

Typically both odd and even page designs, although they could, perhaps, use the same design. If there is a first page requirement, it will be an odd page. The last blank page pagination situation does arise. A last blank page might require an ‘intentionally blank’ statement.

For DITA, and the DOT, a summary of the differences between map types:

Ditamap: Equally likely to use facing pages, or not. Cannot safely assume no facing pages. Less likely to have a first page design, but cannot safely assume no first page design. A simple ditamap booklet might well use the same page designs for ToC and body. A simple ditamap PDF might not use facing pages, and might only need a single page design for ToC and body.

Bookmap: More likely to use facing pages. More likely to use a first page design. The formality of a bookmap might lead to a last blank page with an ‘intentionally blank’ statement.

No map: PDF2 should also be able to create a PDF for a single topic, without either a ditamap or bookmap. PDF2 would need to assume a default design, either ditamap or bookmap. Probably ditamap. Does a PDF of a single topic require a front page and a ToC? Probably not.

The hope and expectation is that this should cover the majority of the requirements for PDF and printed documentation, say 90% plus. Of course, technical documentation can always throw up peculiar situations and requirements.

[robander]

My inclination right now is to mark this closed. I can’t see anything specific that would be implemented based on the design principles above - and if suggestions are made at this point in the thread I’m afraid they will be lost on anybody coming in to try and implement something.

My suggestion - if/when there are specific changes that you’d like to see (with reference to the current behavior that you’d like to change), open a new issue and lay out specifically how / why the PDF should work differently. It might be helpful in those new issues to link to this one as background for your change.

[robander]

Closing this one, any changes to PDF coming out of the discussion above should be covered by the many referenced issues.