texdoc bidi

[Takuto ASAKURA]

Hi again,

> So package authors should pay attention on naming a package
> documentation especially when there is more than a single pdf for a
> package.

yes, this is true, if an author wants to optimize the result for Texdoc.
At this point, Texdoc gives higher scores in the following order in general
(if there are no special adjustments):

1. <package>.pdf
2. <package><known suffix>.pdf
   (where <known suffix> is -doc, -manual, -info, etc.)
3. other names

I would recommend package authors to name <package>.pdf for the most
important document for the package, i.e., either of full documentation
(manual + implementation) or a user manual. However, if there is any
reason an author cannot use the common good names in the above, I'm
fine to add a special adjustment for each specific package.

> I could do that, but I suspect that it is relatively common to start
> with a single foo.dtx (so foo.pdf)  and then later decide to write a
> second user-level manual  leaving the pdf generated from the foo.dtx
> source as just the annotated code listing,

On the other hand, I think David's claim is also true. Actually, I'm
personally testing for a while to add global bonus scores for filenames
containing "manual" and "doc" so that <package>-(manual|doc).pdf can win
over <package>.pdf in general. I don't know in how many cases <package>.pdf
is the most important document and <package>-(manual|doc).pdf are less
important. These global bonuses are still under testing, and I need some
more time to make sure this is effective and not harmful for many cases.

Anyway, I've already added a special adjustment for bidi-doc as a workaround
for the time being.

Best,
Takuto

> On 2020/01/04, at 1:05, Manfred Lotz <manfred at dante.de> wrote:
> 
> Hi Takuto,
> 
> On Sat, 4 Jan 2020 00:17:46 +0900
> Takuto ASAKURA <tkt.asakura at gmail.com> wrote:
> 
>> Hi All,
>> 
>> sorry for my late response.
>> 
>> The contents of the catalog descriptions such as "Package
>> (source|user|) documentation" does nothing to do with the scoring of
>> Texdoc. It only considers whether or not the catalog description
>> exists.
>> 
>> At this point, bidi.pdf wins over bidi-doc.pdf simply because the
>> heuristic scoring prefers <package>.pdf than <package>-doc.pdf in
>> general.
>> 
> 
> Thanks for clarifying. This is an important piece of information. 
> 
> So package authors should pay attention on naming a package
> documentation especially when there is more than a single pdf for a
> package.
> 
> 
>> As a simple workaround, I will adjust the score for bidi-doc in the
>> default configuration file. Please be patient by the next release
>> of Texdoc, which will be in a month (hopefully).
>> 
> 
> Perhaps it would be good to rename the bidi pdf docs like follows:
> 
> bidi.pdf -> bidi-source.pdf
> bidi-doc.pdf -> bidi.pdf
> 
> Then you would not need to adjust scoring specifically for bidi.
> 
> 
> -- 
> Manfred