Collections and packages

[Reinhard Kotucha]

On 2020-07-18 at 12:09:22 -0400, Bob Tennent wrote:

 > It is amazing that tlmgr.1, the only documentation on the
 > management application for a document-preparation system
 > intended to produce beautiful documents is itself a massive,
 > unstructured and, frankly, unusable man page which typesets
 > to no less than 26 pages.

Most features were requested by users.  The size of the man page
somehow reflects the activity of the TeX community and, of course,
the power of the tool itself.

And it's not unstructured at all.  Actions are sorted alphabetically
because it's a reference, not a text book.  The HTML version comes
with an index at least.  Maybe this helps to recognize the structure.

I also disagree when you say that tlmgr.1 is unusable.  This is
definitely not true.  The statement is certainly the result of your
frustration when you didn't find immediately what you looked for.
But this happens to me all the time with other documentation too and
is by far not resticted to documentation within the TeX world.

tlmgr is a powerful tool and there is nothing which can be omitted
from the documentation.  It's biggest strength is that everything can
be controlled from the command line.

Some other powerful tools come with shorter man pages (perl, python)
but almost everything you need to know is in external documents.
The tlmgr manual page describes tlmgr comprehensively.

 > I propose to LaTeX-ify tlmgr.1.  Would that be acceptable?

In order to finally create PDF from the LaTeX file?  If so, just try

  texdoc tlmgr

and you get the PDF version.  PDF versions of manual pages are mainly
created for Windows users who can't use man(1).

If you are still interested in LaTeX-ifying the manual page:

  The source of the documentation is included in tlmgr.pl itself.
  On CentOS or RHEL install pod2latex:

      yum install perl-Pod-LaTeX

  On other systems download the program "pod2latex" from CPAN unless
  you can determine the name of the package containing it.

  Follow the instructions at

      https://metacpan.org/pod/pod2latex

  This works for me:

      cd texmf-dist/scripts/texlive
      pod2latex -full tlmgr.pl
      pdftex tlmgr.tex

  Don't expect high typographic quality.  But without the -full option
  you can provide your own preamble at least.  I suppose that a script
  is needed to fix some problems with Perl's comment characters (#) at
  the end of the file.  I also remember that older versions took a
  backslash from a math font instead from a typewriter font which
  always looked ugly.  I don't know whether this has been fixed in the
  meantime.  I last used pod2latex 12 years ago.

  I don't know whether all the effort is worthwhile but the pod2latex
  approach allows to add \usepackage{hyperref} so that PDF viewers
  display a navigation panel.  This is definitely useful and desired.
  The PDF versions of man pages we currently have in TeX Live don't
  support hyperref.


If text book style documentation is preferred I can only encourage
users who found out how to solve a particular problem with tlmgr
(add a new user tree, install a local font, etc.) to write a TUGboat
article about it.

Regards,
  Reinhard

--
------------------------------------------------------------------
Reinhard Kotucha                            Phone: +49-511-3373112
Marschnerstr. 25
D-30167 Hannover                    mailto:reinhard.kotucha at web.de
------------------------------------------------------------------