Asciidoctor-pdf: Centralised page numbers? (for 'screen' PDFs)

[lurch]

I'm using AsciiDoctor / AsciiDoctor to create a PDF which will be hosted online (i.e. read on a screen, not printed out).
So in my document header I've set:

:media: screen

but I can't see what/any changes have been made to the default behaviour? (https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#theme-related-document-attributes doesn't provide much info)

If a PDF is only intended to be viewed on-screen, does the 'recto' / 'verso' stuff (terms I've not come across before) still make sense?
It would be nice if the page-numbers could always be displayed in the center of the footer, or always at the right of the footer, instead of jumping back and forth between the bottom-right of the page and the bottom-left of the page.

[mojavelinux]

media=screen is the default. In that mode, the recto / verso pages are not handled specially in any way (except for how the converter retrieves the running content).

It would be nice if the page-numbers could always be displayed in the center of the footer

You can achieve that if you customize the theme. For example:

extends: default
footer:
  columns: =100%
  recto:
    center:
      content: '{page-number}'
  verso:
    center:
      content: '{page-number}'  

[lurch]

media=screen is the default.

Perhaps that should be mentioned on https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#theme-related-document-attributes
:wink:

You can achieve that if you customize the theme.

Thanks, I'll give that a go later :+1:

[lurch]

You can achieve that if you customize the theme.

Thanks @mojavelinux , I've given that a go and gotten it working. However I've got a few follow-up questions...

1. According to https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#running-content-header--footer it should be:

footer:
  verso:
    columns: =100%

and yet the

footer:
  columns: =100%

I'm using from your example works fine? Are the docs incorrect, or just missing the footer-columns: info?

1. I've now got slightly more complex header & footer content working in my theme file, and it's kinda annoying having to repeat everything in both the recto: and verso: sections. It would be great if I was able to use either footer-<position>-content or footer-both-<position>-content (and obviously the same for the header).

2. The theming docs mention "defining the key footer-<side>-content: none in the theme." however when I tried

footer:
  recto:
    left:
      content: none

in my theme it displayed none in my footer - was it supposed to read "defining the key footer-<side>-content: null in the theme." ? (which then does what was expected) Or am I misunderstanding?

1. I initially tried adding multi-line content in the header using a quoted string - after some trial and error I found that:

header:
  recto:
    right:
      content: "Line 1 +

Line 2"

works, but other variations (such as omitting either the + or the 'extra' linefeed) squash everything into a single line. Perhaps it should be documented? (while typing up this issue I then found the example in the theming guide of a multi-line footer :slightly_smiling_face: )

1. The theming docs also say: "If the height of the running content periphery is larger than the page margin, the running content will cover the main content. To avoid this problem, reduce the height of the running content periphery or make the page margin on that side larger.". Having to manually specify all 4 of the page-margins just because I want to display a header is kinda awkward. Would there be any reason to not automatically adjust the top-margin to max(page_top_margin, header_height) ? :man_shrugging:

2. What does header-sectlevels: control?

3. By default (?) there's a horizontal rule drawn between the page-content and the footer. Is there a way (using the theme-file) to draw a horizontal rule between the header and the page-content?

4. I wonder if the theming guide would be easier to read if the "how to use a custom theme" came before you started deep-diving into the "Values" definitions? Felt like a bit of a information-overload the first few times I tried reading the page.

5. Similarly, it might be useful if the theming guide had appropriate cross-links to the AsciiDoctor userguide, e.g. https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#code could have a link to https://asciidoctor.org/docs/user-manual/#literal-text-and-blocks and https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#admonition could have a link to https://asciidoctor.org/docs/user-manual/#admonition etc. etc.

I hope you don't mind me jamming all these questions into a single issue :wink: Feel free to create separate issues for each of them.

Thanks in advance for any help!

EDIT:

1. Why does https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#attribute-references introduce {document-title}, when the {doctitle} mentioned at https://asciidoctor.org/docs/user-manual/#doctitle-attribute works equally as well? :wink: Should one of them be preferred over the other?

[mojavelinux]

I hope you don't mind me jamming all these questions into a single issue

General questions are better suited for the mailinglist at https://discuss.asciidoctor.org.

[mojavelinux]

(1) columns can be defined at either level. The setting inherits. I added docs to point this out.

(2) That's already an open issue. See https://github.com/asciidoctor/asciidoctor-pdf/issues/268. I've provided a workaround that only requires one extra line.

(3) We seem to be missing a test for that. I'll open a separate issue to see what's going on and make sure a test gets added to cover it. In the meantime, you should be able to use nil ~ to get the same effect.

(4) You seem to have found the docs for this one. I added a section title to make it easier to find. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#multiple-lines

(5) "Having to manually specify all 4 of the page-margins just because I want to display a header is kinda awkward. Would there be any reason to not automatically adjust the top-margin to max(page_top_margin, header_height)?"

Yes, because then someone would want the opposite ;)

(6) What depth of section level is consulted to set the implicit attribute section-title available to the running content. I added docs for this.

(7) Yes. It's controlled by the border-color/width/style keys under the header key.

(8) I'm sure the theming guide could be reworked. It has grown gradually over time, so it was never really outlined.

(9) We're holding off on this until the new docs site is live at docs.asciidoctor.org, at which time this guide will move there.

(10) document-title is just the main part (not the subtitle). document-subtitle holds the subtitle. doctitle contains both. If you don't have a subtitle, there's no difference between doctitle and document-title.

[mojavelinux]

If you have specific questions, please follow-up using either the mailinglist or dedicated issues.

[lurch]

Thanks so much Dan!