476 landscape

[fsteimke]

Support for landscape orientation for books / articles or individual elements (chapters, tables, figures ...).
Using the role attribute as discussed in issue #476 .

[ndw]

Sorry about the merge conflicts. Sorry about leaving the PR for several months. :-(

I've got a branch where I have it working, I think, but I'm not able to get the output to be in landscape. What PDF formatter are you using?

[frank-steimke]

I am using Antenna House Formatter.Testing takes some time on my side, since i am doing development on a Linux system, but AH Formatter license is for windows only. But i will try to find out about the merge conflicts this weekend.

I'm not sure, but i think i have also successfully tested with the Oxygen PDF Chemistry Formatter which converts to XSL-FO.

[ndw]

Don't worry too much about the merge conflicts, I have a branch where I've resolved them.

Can you send me a .pdf.html file that generates a landscape PDF for you?

[fsteimke]

Yes, but it takes some time.

[ndw]

No rush. I'm trying to do a 2.2.1 today but I'll cleanup and do another release more promptly this time :-)

[fsteimke]

landscape.zip

In this archive you will find

• docbook source
• html generated with my fork of xslTNG which includes the landscape pull request
• CSS from my fork of xslTNG
• PDF generated with Antenna House 7.4 (Windows) from HTML+CSS

I hope it helps.

Greetings, Frank

[ndw]

The only thing that I'm still confused by is article.016. That comes out portrait for me, not landscape. I think that's because the landscape role isn't being added to the class on the HTML element, only the body element.

I'm still using AntennaHouse 7.3, so I guess it could be a bug.

[ndw]

No, putting the landscape keyword in the class on the html element had no effect.

[ndw]

Can you send me the article.016.pdf.html and article.016.pdf output that you get?

[frank-steimke]

Hi Norm, I don’t have access to my development environment yet, since I am in the office. I will take care of it tonight / tomorrow morning Mit freundlichen Grüßen i. A. Frank Steimke, KoSIT Tel. +49 421 361 59 195 E-Mail: ***@***.******@***.***> Von: Norman Walsh ***@***.***> Gesendet: Mittwoch, 2. Oktober 2024 09:13 An: docbook/xslTNG ***@***.***> Cc: Steimke, Frank (Finanzen) 44-A ***@***.***>; Comment ***@***.***> Betreff: [EXTERN] Re: [docbook/xslTNG] 476 landscape (PR #478) Can you send me the article.016.pdf.html and article.016.pdf output that you get? — Reply to this email directly, view it on GitHub<#478 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ATX5HFDWMV5Y2N25TECLKQDZZOMHFAVCNFSM6AAAAABDWV4V52VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOBXG43TQMBWGU>. You are receiving this because you commented.Message ID: ***@***.***>

[fsteimke]

I am still in my office, but ... i'm afraid that the book016.html expected file misses the link to the docbook-paged.css stylesheet for the print media type.

[ndw]

I think the "expected results" are all HTML, not PDF. Have to think about how to fix that.

I upgraded my AHF to 7.4 and I'm still getting portrait output for article.016.pdf...

[fsteimke]

book016.zip

Archive contains HTML and PDF file for book.016. The link to the docbook-paged..css stylesheet for print media was added manually.

[ndw]

I can reproduce some of the expected results. I can get the two landscape pages in book.016.xml for example.

But article.016.pdf is persistently portrait. If I specify landscape instead of A4 article-style on the class attribute on the html element, it comes out landscape, but not if I only add landscape. Which confuses me.

[fsteimke]

I did not understand that recent activity in my forked repository does affect the pull request that i made months ago. But i have learned now. Sorry if that has caused additional confusion.

This is what i did for the attached archive:
476-landscape.zip

• renamed book.014 to book.019 to avoid conflict
• each of the five html files from test/resources/expected got an additional link to the docbook-paged.css styleheet for print media (manual activity).
• render each html file into pdf with Antenna House Formatter 7.4 with "standard options" for PDF generation. This includes the option "Page Orientation: Portrait"

book.019 (the former book.014) has blank first and last pages in portrait orientation. I have checked with the "PDF Option / Page orientation: landscape" setting in AH Formatter. I got also the first and last page blank, but landscape oriented.

[ndw]

I'm not sure why we aren't converging on the problem with article.016. My temptation at this point is to apply the changes you've made so far (possibly copy editing a little), and see where we end up.

[ndw]

I am still very confused. If I follow the command-line instructions to checkout your PR:

git checkout -b fsteimke-476-landscape main
git pull [email protected]:fsteimke/xslTNG.git 476-landscape

Then neither ./gradlew book.015.pdf nor ./gradlew book.015.html produce output that looks like your version from the ZIP file.

[fsteimke]

Yes. Because when you run ./gradlew book.015.html, the generated book015.html file misses the link to the docbook-paged.css stylesheet. I had to add it manually. For this, i had to format the html file. All HTML files in the zip archive are formatted and do contain this additional line. This should be the only difference.

Can you please check this? run ./gradlew book.015.html, add the line

<link href="./css/docbook-paged.css" rel="stylesheet" media="print" />

in the head element, and render it with AH Formatter.

Norm, i simply dont know how to use you test mechanism in a way that the generated HTML files do contain the link to the docbook-paged.css stylesheet for print media type. I am pretty sure there is an easy way, but i don't know it. Running ./gradlew book.015.html will produce an html file which contains only one link to one stylesheet:

link href="./css/docbook.css" rel="stylesheet" media="screen" />

When i would render this file, it would be in portrait, since the whole magic for landscape is part of docbook-paged.css.

[ndw]

Ah. Okay. Sorry the build system is largely undocumented :-(

The build targets for PDF examples are test-name.pdf instead of test-name.html. For example:

./gradlew book.015.pdf

That uses print.xsl (as described in the guide section 2.14 Paged-media (print-output)).

There's a whole lot of CSS for managing page sizes, recto- and verso-pages, page breaks, blank pages, etc. that's included if you use print.xsl. And unfortunately, that interacts with landscape pages in a complicated way. But I think I have it working.

[fsteimke]

Regarding to your last comment, i have some questions:

1. i am afraid that i cannot use ./gradlew book.015.pdf unless i have a AH Formatter licence on my development system, is that correct? If so, this is no option for me.
2. I think that ./gradlew book.015.expected is the only way to create the expected result of transformation. It uses docbook.xsl by default. In other words, the expected result will be for Web and not for print. Which is wrong for book.015to book.019. Is there any way to change the transformation script to print.xsl instead for particular files?
3. Same for ./gradlew test. It uses docook.xsl by default to generate an HTML file and compare it to the expected result. Is there a way to tell the testing machinery that print.xsl should be used for particular files?
4. I saw that you have configured a customization layer for book.014 for release 2.2.1. But i dont understand the steps. Is it possible to create a test customization layer for the five files in question, so that print.xsl will be used instead of docbook.xsl for the expected result as well as for the test result?

[ndw]

If you just want the HTML output for print, you can use test-name.pdf.html as the build target. That will put the HTML in the build/actual directory without trying to format it as PDF.

Testing for print output is definitely not as robust as it could be.

[ndw]

On closer inspection over lunch, it's even worse than I thought. If you want to generate a landscape page in the middle of a flow (for a table, for example), you have to select the @page model that's appropriate for the flow that's in progress (article-flow or book-flow for example). If you just use

@page landscape {
  size: landscape;
}

.landscape {
  page: landscape;
}

you get a landscape page, but you don't get any of the headers or footers that should be on the page. I suppose you might want that, but chances are you do usually want the page number. (If you'd like the headers and footers to be portrait on the otherwise landscape page, that's something else entirely.)

[fsteimke]

I have just checked, and you are right. That's not the desired result. This effect did not show up in the test-cases

I will withdraw this PR. But perhaps you can give me a tip on how to achieve the desired result. Is it a matter of CSS? Or do ihave to work with HTML tables that contain one row each for the header, footer and body?

[ndw]

I'm trying to sort that out. Getting the correct headers and footers in landscape orientation (so lefters and righters from a portrait perspective) would be a little tricky, but it's easy to see how to do that. Getting the headers and footers on the top and bottom of the (portrait) page while the content is landscape is either difficult or impossible, I'm not sure which just yet.

[ndw]

For rotating tables and figures in an otherwise portrait flow, it looks like changing the writing-mode and/or the reference-orientation is a much better solution. It rotates the content but not the headers and footers.

[fsteimke]

I try to understand the test mechanism: how could i customize the transformation that generates the expected result for particular test-cases? For example, set parameters to be used for transformation of particular files. This is motivated by the test-cases for landscape.

I found your test-case customization layer for book.014 in the recent 2.2.1 release at src/test/resources/book.014.xsl. Seems to be exactly what i am looking for. It contains a xsl:message showing that the customization layer is being used.

I made some tests with a result that puzzles me:

• ./gradlew book.014.html: the message shows up, the customization is used
• ./gradlew book.014.expected: the message does not show up, the customization layer seems not to be used
• diff build/actual/book.014.html src/test/resources/expected/book.014.html shows that both files have different content

Is that intended?

[ndw]

No, that sounds like a bug in the test driver. sigh

The expected results are complicated by the fact that they are built with "xspec" specific customizations. These customizations avoid a bunch of differences (the stylesheet version, dates and times, etc.) that aren't relevant but would show up as differences in the report.

It's probably time to refactor the whole test aparatus and try to resolve some of those things, and the customizations, in a less completely ad hoc, tangled way.

[ndw]

My current idea for how to deal with landscape is to add a paged-media-extensions parameter (exact name, tbd) that identifies an additional stylesheet for use in paged media. There will be an AntennaHouse version that supports landscape rotation of tables and figures using -ah-reference-orientation. If you don't use the AntennaHouse extension, the rotation will be accomplished by changing the page master. That rotates the headers and footers, but I don't know any way to deal with that. If other paged media engines provide extensions to deal with landscape in a better way, or if CSS is extended to do it in some standard way, we can adapt.

[fsteimke]

The main motivation for landscape support in DocBook documentation is (at least for me and my staff) the existence of tables or images that are just to wide for A4 portrait pages. We would appreciate the PDF version of out Documents in portrait as default, with the exception of some pages in landscape. The "master page" solution seems to be sufficient for this use-case, as in my very naive approach. I admit that headers and footers would be nice.

The complication arises when you try to put landscape oriented graphics or tables in portrait pages, correct?

[ndw]

I think the real complication is headers and footers. I imagine that this is what most users would expect. But if you rotate the page using CSS @page instructions, you'll get the headers and footers rotated as well.

book.016.pdf

[fsteimke]

I think most people would read the generated PDF online. If you want to read page 4 of your Book 16, you have to rotate either your head or the monitor for 90 degrees.

Why not rotate the whole page with headers, footers and content? See page 5 of the following example:
visualisierungs-templates.pdf

This would be totally fine for me and my staff. In my opinion a good enough solution for "Landscape support in DocBook Documents".

CSS code is simple (as a proof-of-concept it lacks differentiation between left and right side in a book)

/* Support for landscape orientation                            */
@page landscape {
  size: landscape;
    @top-center {
    content: string(DocumentTitle);
  }
   @bottom-center {
    content: 'Seite ' counter(page);
  }
}
.landscape {
  page: landscape;
}

[ndw]

Supporting both flavors makes sense. I think for actual, physically printed books, preserving the running headers and footers in portrait on the page is very, very highly desirable.

[fsteimke]

Sounds good. But it means that we need to distinguish between these two flavors of landscape somehow:

1. page master is rotated (landscape), including headers, footers and content, Poor mans landscape, intended for online PDF.
2. page master is not rotated (portrait). Only content is rotated (landscape) but headers and footers are not. Intended for professional printed books, but unreadable online unless you like to rotate your head :-)

I have updated this PR. Maybe it's not as bad as it looked at first glance for the first flavor (online PDF). But i am still unable to generate the expected files with the link to the docbook-paged stylesheet.

I have also raised an issue for the possible bug in the test machinery (ignored test customization).

[ndw]

I've just pushed #520 which I think addresses the use cases. I'll merge it into main after it passes tests (he says, optimistically :-) ). Please give it a try and let me know what you think.

[fsteimke]

Looks very good. Problem solved, after all. Thank you very much.