[tex-live] texdoc index

[Reinhard Kotucha]

On 2011-12-27 at 06:19:25 -0500, Victor Ivrii wrote:

 > On Tue, Dec 27, 2011 at 5:31 AM, Norbert Preining <preining at logic.at> wrote:
 > > Hi all
 > >
 > >> texdoc is completely broken.
 > >
 > > I disagree. There are some errors but in most cases texdoc works
 > > much better than the old version.
 > >
 > > One only has to add an exception. And you could make the change
 > > yourself and commit it, if it bothers you so much!
 > >
 > > Norbert
 > 
 > I do not think that texdoc is broken. Sure displaying LPPL for plnfss
 > is a funny idea but with a switch -m, -l or -s plnfss.txt will be
 > found as well. Unfortunately existence of texdoc itself remains an
 > esoteric knowledge among many texusers and switches are even more so.

Of course, I was exorbitantly exaggerating.  It's a great thing, though
its behavior is sometimes a bit surprising.
 
 > Sure, LPPL.txt is present only in several doc directories of texlive,
 > and only one such directory (plnfss) does not contain pdf file so
 > probably the problem is only here. The easiest way to fix it would be
 > to produce plnfss.pdf from plnfss.txt

It's not a fix in my opinion but a workaround.  At an earlier
discussion someone proposed to remove the file LPPL.tex.  But can this
be the ultimate solution?  Other packages come with plenty of
non-documentation files too and texdoc somehow has to deal with them
anyway.

Making a new release of plnfss is at the very bottom of my to-do
stack.  Too much happened this year, changing my priority list
completely.  And when I've time to make a new release, I would do it
the same way as with VnTeX: move all non-documentation files to
texmf/source, a directory invisible to texdoc.  However, the main goal
was to achieve that texdoc --list doesn't find too many unrelated
files, not to circumvent problems with texdoc itself.

Look at the debug output:

  texdoc debug-score: ----------
  texdoc debug-score: Start scoring /usr/local/texlive/2011/texmf-dist/doc/plain/plnfss/LPPL.txt
  texdoc debug-score: Name used: plnfss/lppl.txt
  texdoc debug-score: Start heuristic scoring with pattern: plnfss
  texdoc debug-score: New heuristic score: 1. Reason: subword match
  texdoc debug-score: New heuristic score: 0.1. Reason: bad extension
  texdoc debug-score: New heuristic score: 1.6. Reason: directory bonus
  texdoc debug-score: Final heuristic score: 1.6
  texdoc debug-score: Max pattern score: 1.6
  texdoc debug-score: Final score: 1.6
  texdoc debug-score: ----------
  texdoc debug-score: Start scoring /usr/local/texlive/2011/texmf-dist/doc/plain/plnfss/plnfss.txt
  texdoc debug-score: Name used: plnfss/plnfss.txt
  texdoc debug-score: Start heuristic scoring with pattern: plnfss
  texdoc debug-score: New heuristic score: 4. Reason: exact match
  texdoc debug-score: New heuristic score: 0.1. Reason: bad extension
  texdoc debug-score: New heuristic score: 1.6. Reason: directory bonus
  texdoc debug-score: Final heuristic score: 1.6
  texdoc debug-score: Max pattern score: 1.6
  texdoc debug-score: Final score: 1.6
  texdoc info: View comand: /usr/bin/less "/usr/local/texlive/2011/texmf-dist/doc/plain/plnfss/LPPL.txt"


You see that plnfss.txt first gets a much higher score than LPPL.txt
due to the "exact match" but it's obviously discarded later.  I think
it shouldn't be discarded.  Finally both files have the same score
though the system already detected that plnfss.txt is more appropriate
than LPPL.txt.

 > However probably texdoc for a package foo should look first for
 > foo.pdf among all pdfs (unless there is an exception),...., foo.txt
 > first as well among all txts  (unless there is an exception).

I think that an "exact match" should have a higher priority.  I
suppose that this is already intended:

  texdoc debug-score: Start scoring /usr/local/texlive/2011/texmf-dist/doc/generic/vntex/vntex.pdf
  texdoc debug-score: Name used: vntex/vntex.pdf
  texdoc debug-score: Start heuristic scoring with pattern: vntex
  texdoc debug-score: New heuristic score: 4. Reason: exact match
  texdoc debug-score: New heuristic score: 5.5. Reason: directory bonus
  texdoc debug-score: Final heuristic score: 5.5
  texdoc debug-score: Max pattern score: 5.5
  texdoc debug-score: Catalogue details bonus: +1.5
  texdoc debug-score: Final score: 7

Here, scores are cumulative.  It's obviously "bad extension" which
doesn't add its value to the scoring system but instead resets it.
This seems to be unintentional.
 
 > Victor
 > 
 > PS There is a difference between "contains bugs" and "buggy", between
 > "buggy" and "broken" and between "broken" and "completely broken".

Please don't be worried too much about my exaggerations.  Sorry for
the noise.

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