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

[Manuel Pégourié-Gonnard]

Heiko Oberdiek scripsit (17.07.2008 07:14)
> In short:
> There is no way for "texdoc" to find out what is the "better"
> documentation or what the user might want to have.
> 
Agreed.  But in some circumstances (looking for the user manual of a LaTeX
package) the notion of "better" is quite clear (at least in most cases).  So
ideally it should be possible for the user to specify what kind of doc he's
looking for on the command line and have texdoc find and display it (I really
like the find-and-display-on-the-fly mode since it allows very fast access to
the doc).

But for that, we need user (or most probably, developer) input in order to tag
the docs.  There's already kind of such tags in the Catalogue, but texdoc
don't use it atm.  We (TL team) could add such tags manually while
importing/updating packages from the CTAN.  Anyway, I'd like to try this kind
of things, but obviously post-release.

> 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.
> 
Mostly agreed, but not entirely random.  Currently 'texdoc name' begins with
something like

kpsewhich --format="TeX system documentation" name.{,pdf,html,txt,dvi,ps}

(in texlua, but you get the idea).  So there's an order on the file
extensions, that the user can configure.  The value of the TEXDOCS variable in
texmf.cnf is also such that TEXMF/doc/man is searched first and
texmf-doc/doc/english is searched before the rest of texmf-doc/doc/.

Admittedly, this is no very better than random, but hey, we're what we can
before release...

> 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).
> 
Yes.  By the way, texdoc has got two search modes:  the first is what I
described above, the second is what the -s option does: matching 'name' as a
Lua regex against the full paths of files, and diplay files who match and have
the desired extension.  I just tought it could use this second mode as a
fallback even in view mode when it finds no results with the first mode.

> Other ideas for two and more documents
> c) texdoc interacts with the user, textmode based.

That's what I was thinking of when I spoke of a 'menu' mode.

> d) texdoc interacts with the user via GUI.

Anyway, it would be good to have both a command-line texdoc and a nice GUI
frontend, since lots of users are afraid of the command line (but needless to
say here, lots of users prefer the command line too).

> e) texdoc presents a on the fly generated document (PDF, HTML)
>    that shows the different documents with links and perhaps
>    enriched with meta information.

By the way, that's more or less what mthelp (the MikTeX homologue of texdoc)
does: generate and display a html page with, as far as I can see, the results
of a search similar to texdoc -s.  I don't like this for my own use since it's
slow (or maybe I should use a text-based html browser), but maybe others like it.

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

> c), especially d) would be the most comfortable way for the user.
> However, implementation is more expensive, especially portability
> isn't trivial.
> 
Agreed too. Concerning portability, if we use perl/tk for the GUI and texlua
for the textmode, it should be ok (perl/tk is already used by the gui versions
 of the installer and tlmgr).

> Therefore my favourite is a combination of b) and f).
> f) is triggered only if all found documents share the same
> format PDF/HTML.
> 
In an ideal world, all packages would have a pdf documentation, and f would be
great.  Unfortunately, we're not in this kind of world...

> What about using view mode, if there is only one document and
> using list mode, if there are two or more found documents?
> 
It's a good idea.  But I'm hesitating.  From my own use of texdoc, I'm really
inclined to prefer the view mode, but maybe I'm biased.

Thanks for your remarks,
Manuel.