[tex-live] texdoc suggestion for the cool package

[Reinhard Kotucha]

On 8 December 2010 Lars Madsen wrote:

 > Robin Fairbairns wrote:
 > > Karl Berry <karl at freefriends.org> wrote:
 > > 
 > >> (For the future: it's better to write about texdoc things on
 > >> texdoc at tug.org.)
 > >>
 > >>     texdoc cool
 > >>     point to
 > >>     texdoc Content_LaTeX_Package_Demo.pdf
 > >>
 > >> As usual, texdoc is just following the Catalogue here, which says
 > >>
 > >> <documentation details='Package documentation'
 > >>         href='ctan:/macros/latex/contrib/cool/cool.pdf'/>
 > >> <documentation details='EXamples of use'
 > >>         href='ctan:/macros/latex/contrib/cool/Content_LaTeX_Package_Demo.pdf'/>
 > >>
 > >>     as cool.pdf just shows the implementation and the other one is rather 
 > >>     hard to guess.
 > >>
 > >> Perhaps Robin could change the Catalogue to say something like 
 > >> implementation" for the first and documentation for the second, then.
 > >> Robin, wdyt?
 > > 
 > > i'm not entirely sure what's needed; i've made the doc descriptions more
 > > ... descriptive of what the docs seem to be doing.
 > > 
 > > is that enough?
 > > 
 > > r
 > 
 > I've got not idea as to how it is done at the TL end.

Nothing is done in TeX Live.  tecdoc reads the catalogue and assigns
entries with <documentation details='Package documentation' a very
high priority.

Not that I agree with this change (see below), what Karl suggested is
to change the catalogue entry like this:

 <documentation details='Package implementation'
         href='ctan:/macros/latex/contrib/cool/cool.pdf'/>
 <documentation details='Package documentation'
         href='ctan:/macros/latex/contrib/cool/Content_LaTeX_Package_Demo.pdf

 > Just think that a user looking for help on the cool package might
 > not get much help from the cool.pdf file.

The opposite is the case.  Actually, the example file doesn't contain
any information which isn't already present in cool.pdf.  Just ignore
the macro code.  Each macro is explained somehow, even with examples.

I don't think that the proposed change is a good idea.  The file
cool.pdf *is* the package manual and the file
Content_LaTeX_Package_Demo.pdf is exactly what its name implies.  I'm
sure that texdoc's current behavior is what the package author intended.


Robin, something related: entries/v/vntex.xml doesn't contain an entry
for vntex.pdf yet.  Could you add the following, please?

 <documentation details='Package manual' language='en'
       href='ctan:/language/vietnamese/vntex/doc/generic/vntex/vntex.pdf'/>

There is another file, written in Vietnamese, vntex-man.pdf, which
already has a 'Package manual' tag in the catalogue.  This shouldn't
be found in the first place by texdoc.  vntex.pdf is the main manual
and has hyperlinks to vntex-man.pdf and other related files already.

I don't know what to do with vntex-man.pdf.  Maybe Manuel can give
advice.  I didn't find out from the texdoc code how catalogue tags are
handled.  If "manual" has a higher precedence than "documentation", it
would be sufficient to assign:

  vntex.pdf     ==> 'Package manual'
  vntex-man.pdf ==> 'Package documentation'

Manuel, any suggestions?

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