For quotes below: eb ← Eduard Bloch np ← Norbert Preining
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. Sadly, the Debian Technical Committee was not interested in supporting an amendment to the Debian consititution to put documentation within reach of all users: https://linux.community/post/649372 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1066034 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. 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’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 has potential to be useful for users who don’t have a shred of LaTeX knowledge. np> Please bring this up to the author of pdfjam. Eduard apparently tried that first (see the link in the OP). eb> First, what is texdoc anyway? eb> eb> $ man pdfjam | grep texdoc > np> Did I send you that command line? I would normally expect that someone np> using Debian and has considerabl experience, is aware that the correct np> invocation is np> man texdoc np> ? The problem with that is a Debian user (even a veteran) does not generally know of the existence of texdoc (a precondition to running /man texdoc/). eb> A regular user has no idea about this command. Why should we even care? > np> Well, at least in the TeX World it is well known. Even as a LaTeX user, I don’t think I discovered the texdoc command until a decade after starting to use LaTeX, at which point I wished I had learnt about it sooner. It’s the job of documentation to inform users of relevant commands. Since /man pdfjam/ is incomplete, it should inform users about where the rest of the docs are. It should mention “texdoc pdfjam”. np> Ok, I pose you a good question: np> Please come up with a better way to provide 2.9G (!!!) of np> documentation, that is what TeX Live is shipping. np> Make a decent proposal, and send pull requests to the packaging np> infrastructure at github.com/debian-tex/ np> I am anxiously waiting. Anything upstream from Debian can wildly document their tools however they want, or not at all. Sometimes upstream packages do not even have 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 for lack of man page can never be closed. That’s the Debian way. It stops short of actually requiring someone to fix the bug b/c at the same time Debian has a principle that no one is forced to do work. 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 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. np> Because the author of pdfjam has decided so. If you don't like it, np> why don't you stop complaining and simply use a different tool? I np> already sugested one, pdftk. 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 pages often have a “SEE ALSO” section. It would be a good idea to add such a section to the pdfjam man page which references pdftk and pdfunite. The doc bugs I see are numbered below (some of which are not from this thread, as I encountered this thread with some doc bugs in mind). ① The man page contains incomplete BNF: ===8<------------------------------ SYNOPSIS pdfjam [OPTION [OPTION] ...] [SRC [PAGESPEC] [SRC [PAGESPEC]] ...] ===8<------------------------------ The BNF expansion for [OPTION], [SRC], and [PAGESPEC] are missing. That’s a defect. It vaguely says “Detailed information can be found via "pdfjam --help", and also in the web page mentioned below .” It does not say those places are where the missing BNF is. Users expect _detailed_ to mean extraneous detail about how to use a package. But the BNF is extremely basic information that should be defined on the man page, most certainly when the top level BNF is given. Probably the most stark omission here is what [SRC] is. The absolutely most basic information a user needs is the file types the tool operates on. The man page does not even give enough information for users to know whether there is a remote chance pdfjam can be of use to them in the most basic sense. They should not have to dig past the man page to understand the inputs and outputs. ② “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. ③ “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 refused. LaTeX PDF drivers support inclusion of MPS files, so LaTeX users would reasonably expect MPS to be accepted just as well. It’s unclear why MPS files are getting different treatment than JPG and PNG, but the LIMITATIONS AND BUGS section of the man page should probably mention that MPS files are not supported. ④ 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 is where the sole up-upstream bug tracker is, but the places where users are directed to MS Github for documentation should instead mention “texdoc pdfjam” or “texdoc -l pdfjam” so users reach the local readme without using the network, which would also bring them to the readme version that matches the software version that’s installed. ⑤ Docs say: “For more information, including a sample configuration file, see https://github.com/DavidFirth/pdfjam.” Sample configs on Debian systems should go in: /usr/share/doc/texlive-extra-utils/examples/pdfjam/ or /usr/share/doc/texlive-extra-utils/pdfjam/examples/ ⑥ 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.
