Support for landscape pages in PDF

[fsteimke]

I have a document with a CALS table with @orient='land'. A div element with class='landscape' is produced, but without effect in the PDF that i get when HTML is processed with Antenna House. Support for landscape pages would include:

To add a @page rule for landscape in docbook-paged.css. This is already implemented in the CSS for the xslTNG Guide.

@page landscape {
  size: landscape;
}

.landscape {
  page: landscape;
}

A processing instruction for elements that can be part of a flow with landscape orientation. The PI could be <?db orient='Iandscape' ?> or <?landscape ?>. I would suggest the following elements:

• book (the whole document in landscape);
• article (either the whole document, or individual articles in a book);
• chapter, section, appendix;
• table and informaltable (HTML as well as CALS, although CALS offers the @orient attribute as alternative, because I would prefer a uniform solution for all elements);
• figure and informalfigure

For migration from XSLT 1.0 Stylesheets, a legacy PI <? landscapeFigure ?> as in Landscape images from the Definitive Guide should also be supported for figure and informalfigure.

Documentation for this feature in the Reference Guide.

Greetings, Frank

[ndw]

Why is the PI necessary? Isn't adding role="landscape" sufficient?

(I happen to have added the CSS landscape page when tinkering with the PDF of the Guide. I think it makes sense to put that in the "main" CSS.)

[fsteimke]

Because the @role attribute is too valuable for that. It should be available for semantic assignments, especially for block elements such as section and chapter. The page format, on the other hand, is merely a layout specification.

Of course, we could use the role attribute with multiple values, like the HTML @class, e. g. section role='uml:class landscape', but i would prefer the PI as simpler. And after all, this is what Processing Instructions are made for: its an Instruction how to process this element in an PDF workflow.

[ndw]

Processing instructions have their own drawbacks though. It isn't possible to control their placement or content with the schema, so they can go anywhere. (That's generally a feature of processing instructions, but a bug in this sort of situation.) In addition, the semantics are harder to pin down. If

<article>
  <?landscape?>
  <title>...</title>
  <para>p1</para>
  <para>p2</para>
</article>

makes the article landscape, what does this do?

<article>
  <title>...</title>
  <?landscape?>
  <para>p1</para>
  <?portrait?>
  <para>p2</para>
</article>

It's probably an attempt to make the "p1" paragraph landscape. Maybe that could be supported, but the author could equally write:

<?landscape?>
<article>
  <title>...</title>
  <para>p1</para>
  <?portrait?>
  <para>p2</para>
</article>

Which is borderline incoherent.

I see your point about taking user choice away by assigning values to the role attribute. Perhaps extension attributes would be better? OTOH, I'm tempted to suggest that the author should be identifying what the content is, and that should be driving the presentation choices. So I'm back to thinking it's a role value for the author.

Except, of course, that in real-world publishing, sometimes you just need to say "rotate this because it doesn't fit".

[fsteimke]

Well, I understand why you prefer attributes to PIs. It would be good if we could use a common attribute orient as in CALS tables. But how would that be possible? We need to stay compliant with the DocBook standard (talking about version 5.1)

• We can't use any of the efficiency attributes, they are made for conditional / profiled text.
• with the exception of the role attribute, i can't see any of the common attributes from docbook 5.1 that we could use for page orientation.
• we could use a extension element from a different namespace in the info element. Does every element for which landscape print appears to make sense have an info element?
• what do you mean by extension attributes? Sounds interesting. Is it the any attribute from almost any namespace which is part of common attributes in version 5.2?
• If there is no other way and we have to use the @role attribute, than we should allow multiple values similar to the HTML class attribute.

Considering all this, I would vote for an extension attribute, say pdf: orientation for users or the recent version of DocBook, which is 5.2, as the recommended solution. And a substitute for users or DocBook versions prior to 5.2.. For this I would still vote for the PI solution, with well defined rules. A landscape PI applies always to the parent node, combined with a list of elements which do support this PI. It has no effect to elements which are not in this list. Maybe with examples which illustrate the correct usage, although I find that for simple enough. Attribute and PI should not be used together, but when this is the case, the PI will be ignored.

By the way, my use case is the "rotate because it doesn' t fit" case. We have lots of documents with class or sequence diagrams that are best presented in landscape orientation because of their size, while other diagrams of the same type will be in portrait.

I will be on vacation for the next two weeks. I assume that I will rarely be at the computer.

Greetings, Frank

[ndw]

You can put attributes from a different namespace on any element, so that's all I meant: xsltng:orient="landscape" or something like that. I think the stylesheets already assume that the role attribute can be multi-valued, like HTML's class, so that still feels like the simplest solution.

Enjoy your vacation!

[fsteimke]

I think the possibility to put attributes from a different namespace on any element is a new feature of DocBook version 5.2. Therefore, we should not pursue the idea of a specialized attribute in its own namespace.

It never came to my mind that the role attribute could have multiple values. It's is an awesome feature. Taking this into account, i agree that the use of the role attribute is indeed the best solution.

I just made a PR #478 which supports landscape orientation via the role attribute for whole documents or parts of them. There is a short explanation in chapter 2. I have also made an note which explain the multivalue treatment for role.

Greetings, Frank