[tex-live] texdoc doesn't find man pages

[Heiko Oberdiek]

On Thu, Jul 17, 2008 at 01:35:31AM +0200, Manuel Pégourié-Gonnard wrote:

> Werner LEMBERG scripsit (16.07.2008 21:39)
> >> BTW, for some of the programs I also provide PDF files
> >> from the .web files, enhanced by hyperref
> >> in project latex-tds, module knuth:
> >>   doc/knuth/etc/vftovp.pdf (VF, TFM)
> >>   [...]
> > 
> > With other words: man pages should be last in the list of
> > documentation locations 
> 
> I disagree.  The priority of man pages vs others kind of docs should be
> configurable by the user.  I doubt most users are really more interested in a
> program's documented source code than in it's man page.

It depends on the program, example:
* dvitype:
  "man dvitype" is quite worthless, it doesn't even explain command line
  options, that are shown by "dvitype --help".
  However the documented source code contains the description of the
  DVI format, much more interesting.

In short:
There is no way for "texdoc" to find out what is the "better"
documentation or what the user might want to have.

Thus at some time we should deal with multiple results
when calling "texdoc". The current strategy seems to be
"choice by random". Perhaps enough for TL2008 if time is pressing.

Current behaviour of texdoc
---------------------------
Zero documents:
  texdoc prints "Sorry, no documentation found for [...]"
One document:
  texdoc calls the configured viewer.
Two and more documents:
  texdoc randomly chooses the document (probably first found document).

Other ideas for two and more documents
--------------------------------------
a) texdoc prints a list of found documents.
b) texdoc prints a numbered list of found documents
   and there is an option, e.g. -n <num>, meaning
   that texdoc should select entry with number <num>, if texdoc
   finds <num> or more documents, otherwise the option is ignored.
   Thus the user can call texdoc again, this time with option -n selecting
   the document.
c) texdoc interacts with the user, textmode based.
d) texdoc interacts with the user via GUI.
e) texdoc presents a on the fly generated document (PDF, HTML)
   that shows the different documents with links and perhaps
   enriched with meta information.
f) The last point works well, if all documents share the same
   type, especially PDF or HTML, then the overview document is
   called by the right viewer already. Also the overview documents
   could be cached. Meta information in case of PDF could be
   extracted by pdfinfo, for instance.
g) texdoc calls the viewers for all documents (proposal of Werner,
   if I remember correctly).

Easy to implement seems to be a), b), and perhaps g)
The disadvantage of g) is the unknown behaviour of the viewers.
Some are only calling itself once and display one document only.
And the user might not want that texdoc could open lots of
viewers in many new windows.

c), especially d) would be the most comfortable way for the user.
However, implementation is more expensive, especially portability
isn't trivial.

Therefore my favourite is a combination of b) and f).
f) is triggered only if all found documents share the same
format PDF/HTML.

> Anyway, this kind of collision already happens with eg luatex or etex: when a
> user types 'texdoc luatex' does she want to see luatexref-t.pdf (LuaTeX's
> reference manual) or luatex.pdf (the luatex package reference)?  The man page
> vs pdf from .web thing is just another instance of teh same problem.

Yes.

> In the future, I think we should implement a notion of "category" (eg:
> packages, man pages, program reference manual, program documented source code,
> etc.) and allow to set priority for categories, or ask for something in a
> specific category.  We should also create a 'menu' mode for texdoc: display a
> list of all relevant doc for the query and ask the user to choose which one to
> view by just pressing a key.

Yes.

> What already exists in texdoc is the 'list' mode, triggered by the -l or
> --list options: just make a (somehow arbitrary) list of documentation found,
> do not start a viewer, and the 'search' mode (-s|--search) which gives a
> somewhat more comprehensive list and allows to use Lua-style regexes as
> patterns (since texdoc is in texlua).
> 
> The 'view' mode is the default, and for the problem we're talking about it's
> the worse, but I like it since it allows very fast access to the
> documentation.  But since recently, you can choose the default mode in your
> texdoc.cnf file, eg
> mode = search
> if you prefer search mode.

What about using view mode, if there is only one document and
using list mode, if there are two or more found documents?

Yours sincerely
  Heiko <oberdiek at uni-freiburg.de>