Bug#974724: no useful documentation of pdfjam commands
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.
Reply to: