What a long email ... On Fri, 06 Sep 2024, Manny wrote: > eb> The manpage refers to ONLINE documentation. IMHO this should be part > eb> of a package and NOT require a user to establish internet > eb> connection. > > Indeed, docs that are exclusively online are a detriment to the > quality of Debian. I think it’s the Debian Policy Manual that suggests > docs be shipped with Debian, and that they be included with the > package when small, or when large be packaged separately as > $pkgname-doc.
And it is, the man page is included. > Sadly, the Debian Technical Committee was not interested in supporting > an amendment to the Debian consititution to put documentation within > reach of all users: I don't wade into this level of politics. Feel free to do so if you want. > np> Do you expect that pdfjam duplicates the complete documentation of > np> pdfpages? > > This is a case where the docs themselves require substantial technical > knowledge. It is comparable to “use the source, Luke”.. like reading > code to understand how to use the app. So what Eduard is asking for is > not duplication. It’s a user guide, as opposed to docs for LaTeX > insiders. Then, what about you come up with a good user guide? The Debian maintainers package TeX Live, not pdfjam directly. The Debian maintainers are not required to **produce** user guides. So if you WANT a user guide, why not do your part of participating in open source and **write** one if you are missing one? > It’s unclear if pdfjam intends to exclude non-LaTeX users, or if it is > intended to give non-LaTeX users access to LaTeX functionality. If It is intended to do pdf transformations. What else do you ask? > it’s the former, then there should be a clear warning to non-LaTeX > users that trying to learn to use it will make their brain explode. If > it’s the latter, then the docs are unfit for the job. Certainly pdfjam Sorry, that is just plain rubbish statements I ignore. > The problem with that is a Debian user (even a veteran) does not > generally know of the existence of texdoc (a precondition to running Well, it is the same with any of the 400+ commands that TeX Live ships. I cannot educate you about all the things that have happened in the TeX world in the last 20 years. That is your obligation. Not TeX Live's, not Debian's, and far less the maintainers'. BTW, a quick google for latex tex documentation gives you in one of the top places a SX questions and answer metioning texdoc, just as an easy way. > It’s the job of documentation to inform users of relevant commands. The TeX Live guide is packaged and in Debian. You could peruse it to find texdoc mentioned in one of the first pages. Have you read the TeX Live documentation? BTW, it is not in a walled garden either, you can even read it online, or in the texlive-doc packages. https://www.tug.org/texlive/doc/texlive-en/texlive-en.html > a man page. Debian has its own standards and conventions for > documentation. When for example, there is no upstream man page, the > Debian pkg is required by Debian policies to supply one. A bug report Yes, and have you seen them? Most of them are suprisingly short, or just help2man. > The case at hand is an incomplete man page. I don’t think “wontfix” is > an appropriate treatment of a bug report on an incomplete man page It is wontfix on basis of the policy that * Debian packages TeX Live * TeX Live is upstream * pdfjam is *NOT* upstream, it is upupstream * bug reports to TeX Live do not make sense since it relies on upupstream to fix it * Debian maintainers cannot track down 5000+ upupstream authors Thus, at least my policy over many years was to close "upupstream" bug, as they are not relevant to: * the packaging of TeX Live * TeX Live itself > because it seems to imply the bug report lacks merit. Maybe /you/ > won’t fix it and that’s fair enough, but it should persist > indefinitely as a valid open bug report that needs a fix. I strongly disagree. That makes the BTS a dump hole of stuff that never gets fixed, and devoids it of any usefulness. If you have ever worked with a serious software project, you know that an infinite "backlog" is extremely useless and extremely disturbing. > It’s good to suggest pdftk from a user support standpoint, so long as > pdftk’s existence is not used as rationale not to improve pdfjam. Man Go Forth and improve it! Have you sent a patch / PR with an *actual improvement*? It is about documentation, and you seem to care a lot. > ① The man page contains incomplete BNF: It is not a formal grammar. Who cares. That is with many man pages and docs. > The BNF expansion for [OPTION], [SRC], and [PAGESPEC] are > missing. That’s a defect. It vaguely says “Detailed information can be This is not a BNF, why do you think so? It is a synopsis. > ② “pdfjam --help” gives a *different* synopsis than “man pdfjam”. So > the man page BNF is not even completed by the help page. The BNF on > the man page is therefore broken. As said, send improvements to upupstream. > ③ “pdfjam --help” says: “PDF files (JPG and PNG files are also > allowed)”. I see no mention of MPS files. When I try an MPS file, it’s As said, send improvements to upupstream. > ④ References to Microsoft’s walled garden are littered throughout the > docs. It’s fair enough to reference > https://github.com/DavidFirth/pdfjam/issues for bug reports since that Get a life. Reality is that a lot of development happens on github. I am not interested in your religious aversion against github. > ⑤ Docs say: “For more information, including a sample configuration > file, see https://github.com/DavidFirth/pdfjam.” > > Sample configs on Debian systems should go in: If they are not in TeX Live, they are not packaged. End of the story. > ⑥ One of the great benefits of pdfjam is the ability to take a JPG and > embed into a PDF without touching the JPG payload. I am not aware of > any other tool that has that capability. Tools like ImageMagick > “convert” a JPG to PDF in a way that transcodes the JPG, which is > inherently lossy. So pdfjam could highlight that unique feature, if > anything to encourage other similar PDF tool projects to improve. The > ultimate rationale would be to relieve the pdfjam project of pressure > to support non-LaTeX users. The exiftran tool is the only other tool > AFAIK that can manipulate JPG files in a non-lossy way, but it cannot > produce a PDF. As said, send improvements to upupstream. Best regards Norbert -- PREINING Norbert https://www.preining.info arXiv / Cornell University + IFMGA Guide + TU Wien + TeX Live GPG: 0x860CDC13 fp: F7D8 A928 26E3 16A1 9FA0 ACF0 6CAC A448 860C DC13
