Support right-to-left ViewerPreferences

[marcstober]

Explanation

I'd like to be able to create a right-to-left (RTL or in PDF, R2L) document. More specifically, I'd like to be able to set a document to open in a two page layout (which I already can do with pypdf) with the lower-numbered page on the right.

From what I can tell, this would involve adding a /ViewerPreferences dictionary to the "catalog" with a /Direction /R2L entry.

In the Acrobat UI, this is shown as setting the "Binding" to "Right Edge" (in Properties -> Advanced).

Code Example

How would your feature be used? (Remove this if it is not applicable.)

from pypdf import PdfReader, PdfWriter

pdf_out = PdfWriter()

pdf_out.page_layout = "/TwoPageRight"
pdf_out.viewer_preferences.direction = "/R2L" # new feature


...  # your new feature in action!

[marcstober]

I've made a quick proof-of-concept that implements this. You can see it here: main...marcstober:pypdf:r2l

I haven't submitted a pull request because I think a good solution would more generally provide a way to set things on the ViewerPreferences object, not clutter up the API with a method that sets this specific item and value.

If you want to give me some idea of what you'd be willing to include as a new feature, I can try to turn this into a more complete pull request.

[MartinThoma]

@marcstober The PR by pubpub-zz was just merged and will be part of pypdf==3.16.0. I will release that version on 10.09.2023 to PyPI.

[MartinThoma]

@marcstober One part that we're still lacking is a nice documentation for that new feature. Could you maybe write it? You would need to add a docs/user/viewer-preferences.md file. The content is just standard markdown.

Additionally, you would need to add the file to the index: https://github.com/py-pdf/pypdf/blob/main/docs/index.rst

[marcstober]

Thanks for working on this @pubpub-zz. I'm wondering about the create_viewer_preference method. It seems inconsistent with the rest of PdfWriter; none of the other properties have a corresponding "create" method. Maybe it would be more intuitive if the property getter just automatically created the object if needed? I don't see this method in the tests, either, which it probably should be if this is part of the public API. Also, as small detail, I'd at least expect it to be create_viewer_preferences (with an "s").

[pubpub-zz]

see #2167 (comment) about
However, agree with typo :)