[texdoc] Preferring index.html for documentation

Benjamin Berg benjamin at sipsolutions.net
Sun May 3 10:08:59 CEST 2020


I am the author of the SDAPS package[1]. As my documentation is
completely in HTML, I now tried to remove the outdated PDFs, which made
me run into a few issues (e.g. CTAN validator complains).

Either way, when discussing this with CTAN, we noticed that texdoc does
a suboptimal job at finding the documentation. I have an index.html and
further HTML files for each .sty file (generated using sphinx)[2]. If I
search for "sdaps", then texdoc tries to open "FAQ.html". The situation
is better when searching for e.g. "sdapspdf" which will produce a
direct hit and opens "sdapspdf.html".

As using "index.html" is idiomatic in HTML, I think it would be best to
address this by making sure texdoc prefers the correct file.

In the discussion with the CTAN people, the following two possible
solutions came up:
 1. Prefer index.html slightly over other non-matching basenames.
 2. Score index.html as if its basename was "<parent-directory>.html".
    Not sure what should happen if there was both a "sdaps/index.html"
    and "sdaps/sdaps.html". It might make sense to also prefer
    "index.html" as the overview documentation.

Both of these solutions would fix the problem for me. The first seems
simpler (e.g. by adding "goodbasename_list"), but the second is more
idiomatic for HTML.

What are your thoughts on the matter?


[1] https://ctan.org/pkg/sdaps
[2] Online version: https://sdaps.org/class-doc
    (the offline version uses a simpler them that requires less space)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <https://tug.org/pipermail/texdoc/attachments/20200503/39083afe/attachment.sig>

More information about the texdoc mailing list.