Bug#974724: no useful documentation of pdfjam commands

[Norbert Preining]

tags 974724 + wontfix
thanks

Hi

> And who decided to put dozens of separate tools into monster packages?

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.

> 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.

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

> First, what is texdoc anyway?
> 
> $ man pdfjam | grep texdoc

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
?

> A regular user has no idea about this command. Why should we even care?

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

> 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?

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.

> If so, why do you that for non-HTML contents? This does not make sense.
> Why not use sensible-pager? Or "see"?

It uses xdg-open.

> > texdoc pdfpages
> > gives you the documentation of the additional key/value pairs accepted.
> 
> No, it doesn't.

Well ... because ...

> 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

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.

> 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?

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

> 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.

It is, pdfjam clearly states that the KEYS are the key=value pairs from
pdfpages manual.

> 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?

What should be documented?  Maybe
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.

> 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

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.

> > 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.
> 
> Why? $USER installs a basic tool and wants to

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

--
PREINING Norbert  https://www.preining.info
Accelia Inc. + IFMGA ProGuide + TU Wien + JAIST + TeX Live + Debian Dev
GPG: 0x860CDC13   fp: F7D8 A928 26E3 16A1 9FA0 ACF0 6CAC A448 860C DC13

Bug#974724: no useful documentation of pdfjam commands

[Eduard Bloch]

Hallo,
* Norbert Preining [Thu, Nov 26 2020, 01:41:15PM]:
> On Sat, 14 Nov 2020, Eduard Bloch wrote:
> > First, in former times it was easy to find pdfjam because the package
>
> 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.

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?

> > 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.
>
> Using
>   texdoc pdfjam

Interesting. Let's take a tour, demonstrating the ways of documentation
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.

> gives you the README file of pdfjam with additional documentation, and

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
> gives you the documentation of the additional key/value pairs accepted.

No, it doesn't.

$ texdoc pdfpages
Sorry, no documentation found for "pdfpages".
If you are unsure about the name, try full-text searching on CTAN.
Search form: 

$ 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=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?

-- snip --
please see the document
TeX-on-Debian
in the tex-common package, which can be found in
/usr/share/doc/tex-common/
in the pdf, txt, and html format.
-- snap --

$ ls /usr/share/doc/tex-common/
NEWS.Debian.gz  changelog.gz  copyright

Great, another wrong instruction.

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

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.

> > Even the --help output is not helping. It tells a few things about
> > options but it does NOT mention what the actual operations are.
>
> 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.

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?

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

I do now, after learning that README.md is actually installed, just not
trivial to find. One could just put the reference to

Bug#974724: no useful documentation of pdfjam commands

[Norbert Preining]

On Sat, 14 Nov 2020, Eduard Bloch wrote:
> First, in former times it was easy to find pdfjam because the package

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.

> 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.

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?

> Even the --help output is not helping. It tells a few things about
> options but it does NOT mention what the actual operations are.

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

--
PREINING Norbert  https://www.preining.info
Accelia Inc. + IFMGA ProGuide + TU Wien + JAIST + TeX Live + Debian Dev
GPG: 0x860CDC13   fp: F7D8 A928 26E3 16A1 9FA0 ACF0 6CAC A448 860C DC13

Bug#974724: no useful documentation of pdfjam commands

[Eduard Bloch]

Package: texlive-extra-utils
Version: 2020.20200925-1
Severity: minor
File: /usr/share/texlive/texmf-dist/scripts/pdfjam/pdfjam

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.

-- Package-specific info:
IMPORTANT INFORMATION: We will only consider bug reports concerning
the packaging of TeX Live as relevant. If you have problems with
combination of packages in a LaTeX document, please consult your
local TeX User Group, the comp.text.tex user group, the author of
the original .sty file, or any other help resource.

In particular, bugs that are related to up-upstream, i.e., neither
Debian nor TeX Live (upstream), but the original package authors,
will be closed immediately.

   *** The Debian TeX Team is *not* a LaTeX Help Desk ***

If you report an error when running one of the TeX-related binaries
(latex, pdftex, metafont,...), or if the bug is related to bad or wrong
output, please include a MINIMAL example input file that produces the
error in your report.

Please run your example with
(pdf)latex -recorder ...
(or any other program that supports -recorder) and send us the generated
file with the extension .fls, it lists all the files loaded during
the run and can easily explain problems induced by outdated files in
your home directory.

Don't forget to also include minimal examples of other files that are
needed, e.g. bibtex databases. Often it also helps
to include the logfile. Please, never send included pictures!

If your example file isn't short or produces more than one page of
output (except when multiple pages are needed to show the problem),
you can probably minimize it further. Instructions on how to do that
can be found at

http://www.minimalbeispiel.de/mini-en.html (english)

or

http://www.minimalbeispiel.de/mini.html (german)

##
minimal input file


##
other files

##
 List of ls-R files

-rw-rw-r-- 1 root staff 80 Mar 13  2018 /usr/local/share/texmf/ls-R
-rw-r--r-- 1 root root 1436 Sep 22  2013 /etc/texmf/ls-R
-rw-r--r-- 1 root root 3656 Nov 13 22:28 /var/lib/texmf/ls-R
lrwxrwxrwx 1 root root 29 Jun  8 10:31 /usr/share/texmf/ls-R -> 
/var/lib/texmf/ls-R-TEXMFMAIN
lrwxrwxrwx 1 root root 31 Sep 26 22:41 /usr/share/texlive/texmf-dist/ls-R -> 
/var/lib/texmf/ls-R-TEXLIVEDIST
lrwxrwxrwx 1 root root 31 Sep 26 22:41 /usr/share/texlive/texmf-dist/ls-R -> 
/var/lib/texmf/ls-R-TEXLIVEDIST
##
 Config files
-rw-r--r-- 1 root root 1464 Jun 18 22:36 /etc/texmf/web2c/texmf.cnf
lrwxrwxrwx 1 root root 33 Sep 26 22:41 /usr/share/texmf/web2c/fmtutil.cnf -> 
/var/lib/texmf/fmtutil.cnf-DEBIAN
lrwxrwxrwx 1 root root 32 Sep 26 22:41 /usr/share/texmf/web2c/updmap.cfg -> 
/var/lib/texmf/updmap.cfg-DEBIAN
-rw-r--r-- 1 root root 2763 Oct  5 23:29 
/var/lib/texmf/tex/generic/config/language.dat
##
 Files in /etc/texmf/web2c/
total 8
-rw-r--r-- 1 root root  283 Aug 24  2006 mktex.cnf
-rw-r--r-- 1 root root 1464 Jun 18 22:36 texmf.cnf
##
 md5sums of texmf.d
ca40c66f144b4bafc3e59a2dd32ecb9c  /etc/texmf/texmf.d/00debian.cnf
055e06548bac99958d8ab2dd1248f2b4  /etc/texmf/texmf.d/80tex4ht.cnf
1df66bc319cec731e202eaf39f5d85e1  /etc/texmf/texmf.d/96JadeTeX.cnf

-- System Information:
Debian Release: bullseye/sid
  APT prefers unstable-debug
  APT policy: (500, 'unstable-debug'), (500, 'unstable'), (500, 'stable'), (1, 
'experimental-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 5.9.6+ (SMP w/12 CPU threads)
Locale: LANG=de_DE.UTF-8, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /bin/bash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages texlive-extra-utils depends on:
ii  libunicode-linebreak-perl  0.0.20190101-1+b2
ii  python33.8.6-1
ii  tex-common 6.15
ii  texlive-base