Hi,

reporting this as minor here because the usability is severely impacted.

First, in former times it was easy to find pdfjam because the package
description mentioned its uses more explicitly. You searched for "pdf
join" or "pdf flip" and found the pdfjam. That is no longer possible,
long package description does not provide enough clues, basic search
does not find pdfjam.

Second, the documentation is useless. The manpage refers to ONLINE
documentation. IMHO this should be part of a package and NOT require a
user to establish internet connection. There is no offline version of
that README.md as far as I can see.

Even the --help output is not helping. It tells a few things about
options but it does NOT mention what the actual operations are.
Tried to explain this to upstream before but earned only nothing but
harsh treatment. https://github.com/DavidFirth/pdfjam/issues/30
Unfortunately they also removed the shortcut scripts (see online
manual), so looking for pdfjoin executable does not bring you far.

Best regards,
Eduard.

Yes, but now it is part of the TeX Live group and we cannot include the
long description of every single included TeX package in the long
description of the Debian package, it would fill a book.

Using
	texdoc pdfjam
gives you the README file of pdfjam with additional documentation, and
	texdoc pdfpages
gives you the documentation of the additional key/value pairs accepted.

Do you expect that pdfjam duplicates the complete documentation of
pdfpages?

It says that it is any of the many keys of pdfpages, so you need to read
the documentation of pdfpages, which incidentally can be found with the
above command.

So I really don't see what else can be provided ...

Best

Norbert

Hallo,
* Norbert Preining [Thu, Nov 26 2020, 01:41:15PM]:

And who decided to put dozens of separate tools into monster packages?
And adding a few more keywords to descriptions makes it suddenly "a
book" now?
retrieval from users perspective.

Pre-Condition: As a regular user, I want to use a simple tool to merge
(join, concatenate, append...) a couple of existing PDF files. I don't
want to learn Latex language, my PDFs dont have much to do with Latex.

First, what is texdoc anyway?

$ man pdfjam | grep texdoc

-> nothing

A regular user has no idea about this command. Why should we even care?
We install a tool for basic documentation postprocessing, not creating
new stuff with Tex.

Even if the user knows learned this somehow by accident, your command
opens a browser, which wants me to open the MD file in a special editor
which is totally inappropriate. I guess you call sensible-browser there?
If so, why do you that for non-HTML contents? This does not make sense.
Why not use sensible-pager? Or "see"?

Let's assume that $USER figured out that RTFM of "pdfpages" is needed,
where to get it? Maintainer says:

$ texdoc pdfpages
Sorry, no documentation found for "pdfpages".
If you are unsure about the name, try full-text searching on CTAN.
Search form: <https://www.ctan.org/search/>

$ apt search pdfpages
Sortierung... Fertig
Volltextsuche... Fertig
texlive-extra-utils/unstable,unstable,unstable,unstable,unstable,unstable,now 2020.20200925-1 all  [installiert]
  TeX Live: TeX auxiliary programs

texlive-latex-recommended/unstable,unstable,unstable,unstable,unstable,unstable,now 2020.20200925-1 all  [Installiert,automatisch]
  TeX Live: LaTeX recommended packages

And now, where is supposed to come from? (Remember, user perspective!)
Search it online? Like https://duckduckgo.com/?t=ffsb&q=man+pdfpages ?
Nice try, I remember "Passierschein A38" resp. "Catch 22".

Okay, with some luck (and knowledge how to use apt-file) one can find:
texlive-latex-recommended-doc: /usr/share/doc/texlive-doc/latex/pdfpages/pdfpages.pdf

So even after all that guessing one has to install FIFTY megabytes of
docs to learn about a couple of command line options of a simple tool
which does not even have obvious relationship to Latex in the first
place? SERIOUSLY?

And then even when going the hard way with pdfpages docs, it's not
perfectly clear how exactly to convert those documentation into pdfnup
command line options.

And by the way, if this is the way to go (which I doubt) then that way
should be documented in /usr/share/doc/texlive-extra-utils/README.Debian
somehow. Is it? Hardly, IMHO. And what do find there instead?

Why should I expect that? I didn't ever care about what it uses
underneath. I expect it, like any other tool, to document ITS OWN BASIC
operations properly. If that's is too complicated to be stored in a
manpage then please in a easily identifiable README somewhere aside AND
linked from the manpage.

Why? $USER installs a basic tool and wants to
- use it for basic operations (like, merging two PDFs) and
- have a simple doc about
  - those basic commands
  - which is avaible offline and
  - is easy to find.

Or do you expect a car buyer to read the complete maintenance manual
before starting the engine?

I do now, after learning that README.md is actually installed, just not
trivial to find. One could just put the reference to
/usr/share/doc/texlive-doc/support/pdfjam/README.md.gz or any proper
hint to open it into the manpage and --help output.

Best regards,
Eduard.

tags 974724 + wontfix
thanks

Hi

That was a decision back 15 years ago on debian-devel, where I asked
whether we should package each TeX Live package into a single Debian
package or make groups according to the collections of TeX Live.

So, please go back to the archives and search for an email of me
proposing to package TeX Live, must be about 15 years ago.

Then why don't you use a tool that doesn't use LaTeX, but maybe
something else, like pdftk?

Did I send you that command line? I would normally expect that someone
using Debian and has considerabl experience, is aware that the correct
invocation is
	man texdoc
?

Well, at least in the TeX World it is well known.

That is a problem with your mime-type setup, and nothing I can
influence. Look into your mime type associations for .md files. This is
user controlled.

It uses xdg-open.

Well ... because ...

Which you didn't install, right? Despite being a
	Recommends
Sorry, it is up to you if you override the recommendations of the
maintainers to deal with the outcome.

Feel free to use the link to CTAN to only read the one document.

It is, pdfjam clearly states that the KEYS are the key=value pairs from
pdfpages manual.
	If you choose to not install documentation packages which are
	recommended, don't you wonder that you might miss something?
Or something similar?

Ok, I pose you a good question:
	Please come up with a better way to provide 2.9G (!!!) of
	documentation, that is what TeX Live is shipping.
	Make a decent proposal, and send pull requests to the packaging
	infrastructure at github.com/debian-tex/
I am anxiously waiting.

Please bring this up to the author of pdfjam.

The TeX Live Debian Team packages what TeX Live ships.
TeX Live includes what authors ship.

We only accept bugs that are related to Debian packaging or upstream =
TeX Live, but not for bugs that are in single packages (= up-upstream).
Please go ahead and report to pdfjam upstream.

Because the author of pdfjam has decided so. If you don't like it, why
don't you stop complaining and simply use a different tool? I already
sugested one, pdftk.

Best

Norbert

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.

Am 14.11.2020 um 11:17 schrieb Eduard Bloch:

Hi,

Seems anybody else took over maintenance at upstream and the issue was
re-opened. I mark that bug as forwarded and remove the tag wontfix.

H.
--
sigfault

What a long email ...

And it is, the man page is included.

I don't wade into this level of politics. Feel free to do so if you
want.

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 is intended to do pdf transformations. What else do you ask?

Sorry, that is just plain rubbish statements I ignore.

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.

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

Yes, and have you seen them? Most of them are suprisingly short, or just
help2man.

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

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.

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.

It is not a formal grammar. Who cares. That is with many man pages
and docs.

This is not a BNF, why do you think so?
It is a synopsis.

As said, send improvements to upupstream.

As said, send improvements to upupstream.

Get a life. Reality is that a lot of development happens on github.
I am not interested in your religious aversion against github.

If they are not in TeX Live, they are not packaged. End of the story.

As said, send improvements to upupstream.


Best regards

Norbert

We believe that the bug you reported is fixed in the latest version of
texlive-extra, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 974724@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Hilmar Preuße <hille42@debian.org> (supplier of updated texlive-extra package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
Format: 1.8
Date: Thu, 28 May 2026 21:43:45 +0200
Source: texlive-extra
Architecture: source
Version: 2026.20260527-1
Distribution: unstable
Urgency: medium
Maintainer: Debian TeX Task Force <debian-tex-maint@lists.debian.org>
Changed-By: Hilmar Preuße <hille42@debian.org>
Closes: 974724 1091785 1124347
Changes:
 texlive-extra (2026.20260527-1) unstable; urgency=medium
 .
   * New upstream snapshot.
     * Overhauled documentation / manual page for pdfjam (Closes: #974724),
       (Closes: #1091785).
     * Improvements for show-pdf-tags.1 applied (Closes: #1124347).
   * Add patch for arara.1
Checksums-Sha1:
 cb94be99c34321c8ab9fc4e88d945f2014b1973c 3435 texlive-extra_2026.20260527-1.dsc
 a2740efc0dc636328436ffafe90d1d9192f3ae99 19032 texlive-extra_2026.20260527.orig-tex4ht.tar.xz
 b2e5e4f991e4432f8837fb98831dbd5ec8fea664 3208067332 texlive-extra_2026.20260527.orig.tar.xz
 5e878a6acc94172da546abc90db8c5573bb72268 212124 texlive-extra_2026.20260527-1.debian.tar.xz
 9ec3b072ab753dbe73b3e4b158f74cbf77a74861 4972 texlive-extra_2026.20260527-1_source.buildinfo
Checksums-Sha256:
 f509d8c470807c954c28c0c1e4b64d3b40c0105b9512e2aa446d13513bce30ef 3435 texlive-extra_2026.20260527-1.dsc
 2a6f7dc265cd85af11d95403666b07a6d78f113c2365ac873d6f8d83d921f531 19032 texlive-extra_2026.20260527.orig-tex4ht.tar.xz
 7d9c1349eafdad690dab5f41d13e182784150f6f7eddc76e70de4eece47fb345 3208067332 texlive-extra_2026.20260527.orig.tar.xz
 bf8e8631a8159a9d16891a0edfacb083af090fd764e361959babfa6a0c9bbe96 212124 texlive-extra_2026.20260527-1.debian.tar.xz
 f7b85be7e19d822fb1ce0174887be077853942dad235cad84f42be106102890f 4972 texlive-extra_2026.20260527-1_source.buildinfo
Files:
 0338ba94575d46980c3cd8a3c4b63f3c 3435 tex optional texlive-extra_2026.20260527-1.dsc
 1d93a016a36fb2a424b9de72a8109e0b 19032 tex optional texlive-extra_2026.20260527.orig-tex4ht.tar.xz
 87650a28ad31f2fae7f756369b7f5bad 3208067332 tex optional texlive-extra_2026.20260527.orig.tar.xz
 9887c6c93604bd495129884a4c8e42c8 212124 tex optional texlive-extra_2026.20260527-1.debian.tar.xz
 64c056375a50713272a39650dcbd413c 4972 tex optional texlive-extra_2026.20260527-1_source.buildinfo
-----BEGIN PGP SIGNATURE-----

iNUEARYKAH0WIQRKnq6Z0VRDf4bMmAn98EQ6ARgcNAUCahit3F8UgAAAAAAuAChp
c3N1ZXItZnByQG5vdGF0aW9ucy5vcGVucGdwLmZpZnRoaG9yc2VtYW4ubmV0NEE5
RUFFOTlEMTU0NDM3Rjg2Q0M5ODA5RkRGMDQ0M0EwMTE4MUMzNAAKCRD98EQ6ARgc
NDB1APsGp1xi68Cs3I9dB4ReTp2yca/D/iYaI1n2fteb/rhWGQD/bNdWtOI3sRZ1
LovrmGNvkX4xy7OS+/tXaQWTZLkrEg8=
=3hmW
-----END PGP SIGNATURE-----