search

py-pdf / pdfly

CLI tool to extract (meta)data from PDF and manipulate PDF files
BSD 3-Clause "New" or "Revised" License
109 stars 18 forks source link

Just some feedback on pdfly #23

Open Lucas-C opened 1 year ago

Lucas-C commented 1 year ago

Hi!

This is a follow-up of a comment I made there: https://github.com/py-pdf/pypdf/discussions/2171#discussioncomment-6946137

After quickly trying out pdfly, this a humble report of some subjective feedbacks & suggestions I have 🙂

I hope this can be read as constructive criticism, my only wish is for pdfly to become more popular!

  1. pdfly should be advertised more! 😅 This is a very handy swiss army knife that I think would benefit many CLI users, even outside the world of Python. Suggestion: I'm planning to write a short blog post about it. I'm also willing to submit a PR to add a documentation page in pypdf section about it.
  2. The page extraction feature of pdfly is a bit hidden. I only discovered it by carefully reading the pdfly cat --help description. Suggestion: replace Concatenate pages from... by Extract & concatenate pages from... in this repo README.md and in https://github.com/py-pdf/pdfly/blob/0.2.14/pdfly/cat.py#L2, and provide page extraction usage examples in the README.md (I can provide a PR for this)
  3. The page extraction feature is based on Python ranges, which is fine, but means that page indices start at zero, which can be confusing for users (it was for me, because I'm used to other CLI tools where page indexing starts at 1). Suggestion: either switch to indices starting at 1 (non backward compatible, but I think preferable in the end for users) or clearly document this.
  4. Finally, a minor usability point: in pdfly cat --help the newlines present in the original command docstring are removed, making the help text quite dense & difficult to read. Also, some "Page range expression examples" are not well aligned in my terminal, and indices colors are inconsistent. Suggestion: I can submit a PR to try to improve this help text readbility, maybe at the cost of removing some content.

What do you think about all this @MartinThoma? 🙂

MartinThoma commented 1 year ago

pdfly should be advertised more!

I agree :-) I've added a few small parts:

I'm happy for more :-)

The page extraction feature of pdfly is a bit hidden

I agree that cat is way more powerful than it initially looks. I'm open to adjustments of the help text and the new docs: https://pdfly.readthedocs.io/en/latest/user/subcommand-cat.html

[cat PageRange]: either switch to indices starting at 1 or clearly document this

I'm torn here. In the end, I'm rather certain that users will be (Python) developers. Hence once it is clear that it's an index / a Python range object, it should be rather clear. I currently tend rather to improve documentation.

newlines of pdfly cat --help

Yes, I know it looks horrible. I would be very happy if you could fix that. If it doesn't work to fix the formatting, I suggest to link to https://pdfly.readthedocs.io/en/latest/user/subcommand-cat.html within the help.