Introduction

The purpose of most of this account is to examine and explain the treatment of what are often called portrait and landscape pages in a PDF file when they are handled by the filtering subsystem on a jessie/stretch/buster CUPS printing system. On wheezy the page management of rotation by pdftopdf is significantly different.

Portrait and landscape are not clearly defined technical terms. Generally speaking, they refer to the way a rectangular object is normally orientated so that sense can easily be made of it. An A4 sheet of paper with text parallel to the short edge would held in portrait mode, short edge horizontal. With text parallel to the long edge, a 90 or 270 degree rotation would take the sheet to landscape mode for ease of reading.

Portrait and landscape are conventions to describe what we see displayed. Beware of using the phrase "landscape printing". This openSUSE page explains why.

The Role of pdftopdf

Printers, even modern IPP printers, have limitations. Overall, they cannot directly scale the text in a PDF, directly do N-up printing, directly rotate a page or directly use a specific font such as freefont when printing a text file. It is not that they could not be manufactured to do such things; they just don't (in general).

Portrait and Landscape Pages in a PDF

A PDF file with mixed orientation pages would be useful to have. mixed.pdf can be downloaded for you to use.

The file has three document pages. Information on each page can be displayed with pdfinfo:

pdfinfo -f 1 -l 3 mixed.pdf

For the first page:

Page 1 size: 595 x 842 pts (A4)
Page 1 rot: 0

The page width is less than its height; it is a portrait page. rot: 0 tells a PDF viewer not to rotate the page. The page would be easily viewed without any rotation.

The second page has:

Page 2 size: 841.89 x 595.28 pts (A4)
Page 2 rot: 0

This is a landscape page because its width is greater than its height. There is no rotation done by the viewer. This is another easily viewable page.

Lastly:

Page 3 size: 595 x 842 pts (A4)
Page 3 rot: 90

This is a portrait designed page but the viewer rotates it 90 degrees clockwise for easy viewing, making it a landscape page.

Printing Portrait and Landscape Pages

Many printers take paper and feed it through the printer short edge first so that text is printed parallel to this edge. For suitably sized paper, page 1 should produce a satisfactory printout. On the other hand, pages 2 and 3 will probably have some part of the right-hand portion of the image not printed if they are sent as-is to the printer.

There are two solutions the printing system could adopt to overcome this problem. One is to rotate document pages 2 and 3 relative to the printer page before printing them. The second is to alter the images of document pages 2 and 3 to make them fit the width of the medium they are being printed on.

pdftopdf and Autorotation

A good way to appreciate what pdftopdf on jessie/stretch does to fit an image on a page of paper is to use cupsfilter. A PPD file, test.ppd, is available for this test and later ones; or you can provide your own.

Page 1 hasn't been touched; the rotation field still has 0. Page 2 would now be rotated 270 degrees clockwise (90 degrees anticlockwise) when viewed. Page 3 has also been rotated 90 degrees anticlockwise and this cancels out its existing 90 degree clockwise rotation.

The autorotate feature is the only way a PDF with mixed orientation pages will be printed correctly when sent to a printer with lp/lpr or from some applications.

and repeat the previous cupsfilter command. You should observe that the rotation is now 90 degrees clockwise. Deleting or commenting out the line gives the same result.

Autorotation can be dispensed with by using -o nopdfAutoRotate-default or -o pdfAutoRotate-default=off when setting up a print queue or, on a job-to-job basis with lp/lpr, by -o nopdfAutoRotate or -o pdfAutoRotate=off. There is no way to turn it off from an application. Test with

The landscape and orientation-requested Options

The direction of rotation is governed by *LandscapeOrientation in the PPD file. Minus90 rotates all pages in a PDF file 90 degrees clockwise; Plus90 rotates by the same amount but anticlockwise. *LandscapeOrientation is part of Adobe's PostScript Printer Description File Format Specification.

However, the orientation-requested=N option always rotates every page in a file in an anticlockwise sense. *LandscapeOrientation is not consulted by it. orientation-requested=N is an IPP attribute specified in rfc8011.

pdftopdf acts on the landscape and orientation-requested=N options whether or not autorotation (which is applied after either of these two options) is operative. The following command with *LandscapeOrientation as Plus90 in test.ppd might prove instructive:

Page 1 is first rotated 90 degrees anticlockwise by orientation-requested=4 and then autorotation applies a further 90 degrees anticlockwise rotation. The other two pages are rotated 90 degrees anticlockwise by orientation-requested=4 but then autorotation has nothing to do, so no further rotation takes place.

The fit-to-page Option

Suppose you want pages 2 and 3 of mixed.pdf to be printed with the text parallel to the short edge of the paper and also for them to fit on the sheet. Autorotation will have to be off for that.

The Landscape and Portrait Options in Applications

The printing dialog of a graphical application usually offers Landscape and Portrait options. The meaning attached to these two words when printing can differ from what CUPS means and also have different meanings for different applications. Not only that, but Portrait and Landscape may be instuctions to be acted on by the application and not the printing system.

For example, Okular and Qpdfview rely on the printing system to process their Portrait and Landscape options.

Okular converts a PDF to PostScript before sending it to CUPS. Its Portrait option sends -o portrait to CUPS. This option is unknown to CUPS (which ignores it) and there is no rotation of any page. Its Landscape option sends -o landscape to CUPSand this is acted on as described above. The Portrait and Landscape instructions play no part in the production of the PostScript file.

Qpdfview does not modify the original PDF file. It simply sends it off to be processed by the printing system with the options selected in its print dialog.

On the other hand,

LibreOffice and applications using the GTK print dialog construct a PDF to be sent to the printing system. Portrait and Landscape determine how the PDF is formed and the printing system has no knowledge of this. For example, Landscape with LibreOffice produces a PDF landscape page with the text parallel to the page's long edge.

Autorotation with pdftopdf still functions as usual no matter how the applications themselves deal with their Portrait and Landscape options. This could be a factor in the apparent decrease in bug reports involving applications and page rotation.