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.