[texdoc] texdoc and man pages

[Reinhard Kotucha]

Manuel Pégourié-Gonnard writes:
 > > Manuel, BTW, it's quite unfortunate that texdoc finds a man page for a
 > > particular program which also comes with texinfo documentation too
 > > (man\man1\dvips.pdf in this case).  These man pages are often
 > > incomplete and out-of-date.  I suggest to add the volume number to the
 > > file name, for instance "dvips.1.pdf".  This is quite straightforward.
 > > It's always problematic if two different files with the same name
 > > exist in a TeX system because some people might want to use kpathsea
 > > in order to find them.
 > > 
 > There are several cases of such duplication in docfiles: man pages and
 > info manuals, engines (etex, luatex) and LaTeX packages, etc. (Hard to
 > automatically list all the relevant cases, since a lot of unwanted
 > thinks such as Makefile's end up as docfiles currently...)

Hi Manuel,
yes, texdoc finds too much indeed currently.  Maybe you could look at
http:/tug.org/~kotucha/read-lsr.tlu.gz again.  The approach is quite
different, here only files with particular extensions are searched.
One might claim that READMEs are not found but I don't think that it's
really necessary.  Often they contain installation instructions,
copyright messages, and similar things, but very rarely real package
documentation.

Unfortunately there are many name clashes, many files are called
manual.pdf, for instance.  I'll come back to this issue below.
 
 > I want to try and address them in a coherent way, but have no time to do
 > it right now.
 > 
 > Just systematically renaming as XXX.1.pdf is not a so good solution
 > since it means you have to think to add the 1, and you will never think
 > about that if you are a poor windows user. 

First of all, most Windows users invoke programs from a GUI and don't
need manual pages.  And those who invoke programs from the command
line certainly will certainly bot be overstrained if they have to
search for XXX.1.pdf.  Those who are using the CLI nowadays have also
some experience with Unix. 

Regarding file names, I'm very convinced that adding the volume number
to the file name is the only reasonable solution.  You have to
recognize that we are talking about two very different things:  File
names and texdoc.  What I'm most concerned about are file names.  They
should be unique, if possible.

Please keep in mind that some people write their own tools.  Unique
file names make life much easier.  You deliberately produced new name
clashes because at a first glance it looked easier to deal with them
in texdoc.  Maybe someone will write something like texdoctk from
scratch, but should he be forced to use the same table-lookup mess
which already broke texdoctk's neck?

If we are talking about file names, we should forget texdoc completely
for a while.

 > I have to put aliases to the real info manual in order to override
 > the man page, but here too I need time to find the list. If you
 > provide me with a list of man pages which should be overridden my
 > info manuals, I can incorporate it rapidly.

IMO this approach is completely wrong.  Unfortunately the aliases
cannot be avoided completely, but the preferred way to solve problems
is to provide an algorithm rather than to use table lookups.  The ls-R
parser mentioned above sorts search results by precedence.  A PDF file
has a higher precedence than a DVI file.  It can be easily adapted to
look for /.*\.[1-9]\.pdf/ files too and the priority can even be
changed at any time.

 > Also, I thought some time of adding (configurable) bonus/malus rules
 > such as "if there is /man/ in the path, then prefer another document in
 > case many documents match". No sure if it would be a good idea.

This is more difficult than necessary.  You have to evaluate the path
because file names are not unique.  But you introduced the problem
deliberately.  A big mistake, IMO.

As I mentioned above, unfortunately there are many files with the same
name (manual.pdf).  We discussed this issue some time ago with Heiko
(it bothered me that the hyperref manual was called "manual.pdf") and
Heiko explained in detail why the user manual cannot be called
"hyperref.pdf".  The problem seemed to be unsolvable.  However, if you
run "texdoc hyperref" nowadays you'll see that Heiko solved this
problem brilliantly.

This is indeed the ultimate solution and I hope that more people
follow this approach.  It reduces the number of table lookups
(aliases) dramatically.

 > If you want to discuss these issues further, please start a new
 > thread in the texdoc mailing list.

I'm concerned about file names in the first place, it actually has
nothing to do with texdoc at all.

Regards,
  Reinhard

-- 
----------------------------------------------------------------------------
Reinhard Kotucha			              Phone: +49-511-3373112
Marschnerstr. 25
D-30167 Hannover	                      mailto:reinhard.kotucha at web.de
----------------------------------------------------------------------------
Microsoft isn't the answer. Microsoft is the question, and the answer is NO.
----------------------------------------------------------------------------