[texdoc] Preferring index.html for documentation

Takuto ASAKURA tkt.asakura at gmail.com
Mon May 4 07:15:15 CEST 2020

Hi Benjamin,

I found only 12 "index.html" under the latest TEXMFDIST:

	$ find /usr/local/texlive/2020/texmf-dist/ -name 'index.html'

Therefore, implementing a special feature for this sounds unreasonable.
I can add some new adjustments instead (but the results for the above
packages (latex-brochure, bosisio, jadetex, ...) look already reasonable
to me.)

Currently, I can't find your "index.html" under the doc dir for sdaps:

	$ ls /usr/local/texlive/2020/texmf-dist/doc/latex/sdaps/
	README           sdapsbase.pdf    sdapslayout.pdf
	sdapsarray.pdf   sdapsclassic.pdf sdapspdf.pdf

If you have any preferred document for the result for Texdoc, possibly
after updating your package, I can optimize it for you, so please let
me know.


> On 2020/05/03, at 17:08, Benjamin Berg <benjamin at sipsolutions.net> wrote:
> Hello,
> 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?
> Benjamin
> [1] https://ctan.org/pkg/sdaps
>    https://github.com/sdaps/sdaps-class
>    https://sdaps.org
> [2] Online version: https://sdaps.org/class-doc
>    (the offline version uses a simpler them that requires less space)

More information about the texdoc mailing list.