[texdoc] texdoc pdftex

[Reinhard Kotucha]

Manuel Pégourié-Gonnard writes:
 > Manuel Pégourié-Gonnard a écrit :
 > > Reinhard Kotucha a écrit :
 > >> Karl Berry writes:
 > >>  > Hi Manuel -- I suggest texdoc pdftex be special-cased to pdftex-a.pdf,
 > >>  > instead of bringing up the man page.
 > >>
 > Done. Actually, there were already aliases
 > 
 > alias etex-ref = etex_man
 > alias pdftex-ref = pdftex-a
 > alias luatex-ref = luatexref-t
 > 
 > so just adding -ref to the name brought up the user manual. I now added
 > 
 > alias etex = etex_man
 > alias pdftex = pdftex_a
 > alias luatex = luatexref-t
 > 
 > thought I'm don't like this very much, since it "hides" the man pages.

Hi Manuel,
it's better than the old version.  There is no need to make the man
pages more visible.  Unix users will still use man(1) in order to read
them.  The pdf files are only good for Windows users, so why bother
Unix users with them?  The man pages rarely contain package
descriptions, hence there is nothing wrong to treat them separately,
for instance by a "--man" switch.

 > > Nope, you're no the only one. I have plans to change that, just no time
 > > to do it atm. I'll probably have more time in two weeks when I'll be
 > > done with my teaching-related tasks.
 > > 
 > Well, I already checked how many conflicts there are with manpages, and
 > if I checked it correctly, there are 185 of them. So I will follow
 > Reinhard suggestion and change the man->pdf makefile in order to produce
 > XXX.1.pdf instead of XXX.pdf. (The list is attached in case you're
 > interested.)

Thank you very much!

 > Then my ideas are to change texdoc's search routine in order to look for
 > XXX.1 and XXX.5 as well as for XXX when XXX is asked. This way, man
 > pages will also be found, but without "hiding" other pages. Then I may
 > check in the sort routine and give low priority to man pages.

Ok, a low priority is fine, a "--man" option is probably a better
choice because man pages an package descriptions are two different
things. 

 > >> texdoc is currrently as unmaintanable as texdoctk.  It depends on
 > >> table lookups instead of algorithms, which is always wrong, IMO.
 > >>
 > > I don't agree with that, but I won't discuss this today, no time.
 > > 
 > To be a bit more explicit, without entering a lengthy discussion: I
 > don't believe we can solve all the doc-finding problems in a purely
 > algorithmic way, since we can't rely on any file naming convention. So
 > some table lookup will always be necessary, and we shouldn't be afraid
 > of them. The points are:
 > 
 > - Use algorithmic methods when we can, and for the man pages you're
 > right, it's a perfect case for an algorithmic method since we control
 > (part of) the file names.
 > 
 > - Make the "database" maintenable. In this respect, I do think
 > texdoc.cnf is much more maintenable than the old texdoctk.dat: it
 > contains less information, and at least no redundant information.

It all depends on what you want to find.  The old shell script didn't
make use of table lookups at all and most people had been happy with
it.  If a particular file had not been found, running "texdoc -s"
printed a list of related files to screen, no table lookups involved
too.

Your alias mechanism can help to provide better results by default but
it shouldn't be overstressed.

Regarding "documetation" within .sty files, I fully agree with Robin.

Files outside the doc tree are always hard to maintain because
maintaining a database is necessary in this case.  I wouldn't try to
make everybody happy, at least if you regard texdoc as a documentation
browser, not as a source code browser.

If you think that providing a source code browser makes sense, it's
certainly not a big deal to provide one for Windows.  On Unix I get
exactly what I expect when I type

     $ less `kpsewhich hyperref.sty`

or
     $ less `kpsewhich hyperref.dtx`

Shall I provide such a program?  Something called "texsource"?  I can
do it easily.  If yes, it doesn't make sense if "texdoc" and
"texsource" overlap.  If there is no dedicated documentation in the
doc tree, people can look into the sources.

What do you think?

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