[texdoc] texdoc and man pages

[Reinhard Kotucha]

Manuel Pégourié-Gonnard writes:
 > > 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.
 > 
 > This is already the approach used by texdoc, you probably only changed
 > the set of extensions searched, which can already be done in texdoc.cnf.
 > Please please do read the current code and/or ask questions about how it
 > works before rewriting stuff form scratch.
 > 
 > Could we please proceed in the following way ?
 > 1. decide what should be done
 > 2. then and only then, write code for it
 > Here step 1 is the hard part, not step 2.

Hi Manuel,
maybe it's too long ago so that you forgot it already: This is not new
code, it's a few months old.  I have written it at the same time when
you revised Frank's code.  You probably remember that I first wrote a
tlpdb parser but then Norbert told me that there is no texlive.tlpdb
in Debian.  I then wrote the ls-R parser.  There had been a few
reasons to do it.  First, of course, I didn't know that you had been
working on it at the same time and I assumed that you can use the code
or parts of it.  One important feature of the parser is that the
front-end can be replaced by another one, for instance one which reads
tlpdb, while most of the filtering is done by the back-end, so that
you get similar results when parsing ls-R, tlpdb, or the file system.

I also had performance in mind and I think that the parser is quite
efficient.  But the main reason I wrote it was to allow you to play
with it.  Of course, I deliberately wrote it from scratch because I
wanted to provide a piece of code for evaluation which is based on my
ideas how to do things.  You still can compare the parser with yours
(if you disable aliases) and see that the results are not exactly the
same.  And I don't think I wasted my time.  Since we are now
discussing such things again, it's quite nice to have a piece of code
which illustrates my ideas.

 > > One might claim that READMEs are not found but I don't think that
 > > it's really necessary.
 > 
 > Random example: texdoc pax.

Interesting.  When I uploaded VnTeX to CTAN, Robin asked me to rename
README to README.txt and upload again because files without any
extension are a pain for Windows users. 

Most READMEs do not qualify for texdoc.  I fear that it's too much
work (and I fear that you neglect your thesis) but maybe it's better
to "mv README README.txt" in ctan2tds if, and only if, the README
contains useful information for end-users.

 > I you want to talk about actual file names and locations, I think
 > files such as Makefile's have nothing to do in the doc/ tree and we
 > sould care about it in ctan2tds or such.

Be very careful when you are going to remove them.  You have to find
out what they are supposed to do.  For instance, there is
texmf-dist/doc/generic/vntex/tests/Makefile.  It would be nice if I
could provide the files the Makefile produces, but the amount of disk
space needed is enormous (see http://vntex.sf.net/fonts/samples ).

You might also be confused by .tex files in the VnTeX doc tree.  The
purpose is to provide a print version.  There are print versions in
PDF already which are using \usepackage[monocrome]{color}.  But this
is not enough, some people have a duplex printer and some people
prefer letter to A4.  Hence it make sense to provide the sources.

However, if the .tex files are in the source tree, nobody knows that
they exist at all.  The more I talk about this issues, the more I'm
convinced that Heiko's approach is the ultimate solution.  Everything
not supposed to be found by texdoc could be moved to the source tree
then.  And people will find the files though.  I'll discuss it with
Thanh.

Again, be very careful when removing files from the doc tree.

 > > 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.
 > > 
 > As you're certainly aware, we cannot expect every single author to
 > be as responsive as Heiko.

Of course, there is a lot of old stuff we have to take as it is.  But
isn't it quite strange that the pstricks guys asked you for an alias
because "texdoc pstricks" didn't work instead of providing a file
pstricks.pdf?  It seems that Heiko's solution lacks advertising.  

 > I'll answer to the rest later, need more time to think about it.

Ok.  But please keep one thing in mind:

   kpsewhich -format='TeX system documentation' dvips.pdf

and 

   kpsewhich -format='TeX system documentation' dvips.1.pdf

provide different results.

If there are two different files with the same name, the result is
unpredictable.  That's all I'm concerned about.

And does it really matter at all whether texdoc derives the
information (that a particular file is a man page) from the file name
or from the path?

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