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