[texdoc] Preferring index.html for documentation

[Benjamin Berg]

Hi Takuto,

it has been quite a while, but I finally uploaded a new bundle to ctan.

In this bundle, I simply placed the HTML documentation into an "html"
subdirectory. I also added a "sdaps.html" page that redirects to
"index.html" using a <meta> tag.

This way texdoc finds "sdaps.html" for the keyword, and the user will
be correctly redirected to the index page. That seems like a reasonable
solution for the problem at hand.

Benjamin

On Mon, 2020-05-04 at 14:15 +0900, Takuto ASAKURA wrote:
> Hi Benjamin,
> 
> I found only 12 "index.html" under the latest TEXMFDIST:
> 
> 	$ find /usr/local/texlive/2020/texmf-dist/ -name 'index.html'
> 	/usr/local/texlive/2020/texmf-dist/doc/latex/latex-brochure/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/latex/bosisio/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/otherformats/jadetex/base/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex4ht/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tds/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex-virtual-academy-pl/idx/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex-virtual-academy-pl/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex-virtual-academy-pl/fonty/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex-virtual-academy-pl/latex2e/macro/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/generic/tex-virtual-academy-pl/poczatki/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/fonts/fontname/index.html
> 	/usr/local/texlive/2020/texmf-dist/doc/texlive/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.
> 
> Best,
> Takuto
> 
> > 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)
> 
> 

-------------- 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/20211110/3bae1a88/attachment.sig>