texdoc plain about texdoc

[kberry]

I don't think it's a good idea to wait for some other document to materialize before fixing texdoc plain to do something useful. I stand by my suggestion of gentle, because it is the shortest useful one I know of. However, I don't object to making the alias go to texbytopic or teximpatient. The fact that results 2 and 3 (fontch) were also not useful (wrt "plain") is what made me suggest an alias. But if you want to adjust enough scores so that gentle, or something else, floats to the top, ok by me. That seems like more manual intervention to me than an alias would be, but whatever. docsurvey is nice, but it's about all kinds of things, not just plain. I think running "texdoc plain" should return something about plain, specifically. tex-nutshell is also nice, but it's much more about primitives, and not the plain macros. So I don't think it should be the top result for "plain". My $0.02 FWIW ... -k

[muzimuzhi]

After checking the content of plain.pdf from inputnormalization package, it seems to me it's uploaded to CTAN by a mistake. I've reported this to the package author, see zauguin/inputnormalization#1.

Instead of aliasing (if it's considered needed even when plain.pdf is removed), I suggest to add a negative score to inputnormalization/plain.pdf, because only aliasing to gentle/gentle.pdf is unfair for other plaintex docs like tex-nutshell/tex-nutshell.pdf and texbytopic/TeXbyTopic.pdf:

# executed in an incomplete texlive/basic-tex installation
$ texdoc -lM plain
texdoc -lM plain
plain	4.0	/usr/local/texlive/2022basic/texmf-dist/doc/latex/inputnormalization/plain.pdf
plain	4.0	/usr/local/texlive/2022basic/texmf-dist/doc/plain/gentle/gentle.pdf		The document itself
plain	4.0	/usr/local/texlive/2022basic/texmf-dist/doc/plain/tex-nutshell/tex-nutshell.pdf		The document itself
plain	4.0	/usr/local/texlive/2022basic/texmf-dist/doc/plain/texbytopic/TeXbyTopic.pdf		The book itself
plain	2.5	/usr/local/texlive/2022basic/texmf-dist/doc/plain/pgfplots/pgfplotsexample-plain.pdf
plain	2.5	/usr/local/texlive/2022basic/texmf-dist/doc/xetex/unimath-plain-xetex/unimath-plain-xetex-doc.pdf		Package documentation
plain	1.8	/usr/local/texlive/2022basic/texmf-dist/doc/plain/tex-nutshell/README		Readme
plain	1.8	/usr/local/texlive/2022basic/texmf-dist/doc/plain/texbytopic/README		Readme
plain	1.0	/usr/local/texlive/2022basic/texmf-dist/doc/man/man1/mtx-plain.man1.pdf
plain	1.0	/usr/local/texlive/2022basic/texmf-dist/doc/context/scripts/mkiv/mtx-plain.html
plain	0.3	/usr/local/texlive/2022basic/texmf-dist/doc/xetex/unimath-plain-xetex/README.md		Readme

[wtsnjp]

Thanks for the information, you two.

Regardless of whether the inputnormalization documentation is removed or not, it is possible that a package with a doc file named plain.<ext> can be added in the future.

As far as I can see from that list, there are three useful documents that describe plain TeX itself: gentle, tex-nutshell, and texbytopic. What do you think about adding a tie-breaking alias to these three?

[muzimuzhi]

[...], it is possible that a package with a doc file named plain. can be added in the future.

It's also possible that plain.<ext> is really about plain TeX.

As far as I can see from that list, there are three useful documents that describe plain TeX itself: gentle, tex-nutshell, and texbytopic.

The list I shown above is incomplete, because I'm working on an incomplete texlive installation. For example impatient.pdf from https://ctan.org/pkg/impatient is missing. impatient also has two translations, in cn and fr.

Thus I still suggest to add a small negative score to inputnormalization/plain.pdf, and depending on whether it's related to plain TeX, adjust score for the future plain.<ext> file.

[wtsnjp]

I have a complete TeX Live installation (TL2023 pretest) locally, and currently, the top 10 results for texdoc -l plain are as follows:

$ texdoc -l plain
95 results. Display them all? (y/N) y
 1 /usr/local/texlive/2023/texmf-dist/doc/latex/inputnormalization/plain.pdf
 2 /usr/local/texlive/2023/texmf-dist/doc/plain/font-change/font-change.pdf
   = Package documentation
 3 /usr/local/texlive/2023/texmf-dist/doc/plain/fontch/fontch.pdf
   = Package documentation
 4 /usr/local/texlive/2023/texmf-dist/doc/plain/gentle/gentle.pdf
   = The document itself
 5 /usr/local/texlive/2023/texmf-dist/doc/plain/getoptk/guide.pdf
   = Package documentation
 6 /usr/local/texlive/2023/texmf-dist/doc/plain/gfnotation/GFnotation-doc.pdf
   = Package documentation
 7 /usr/local/texlive/2023/texmf-dist/doc/plain/happy4th/happy4th.pdf
   = Package output
 8 /usr/local/texlive/2023/texmf-dist/doc/plain/hyplain/hydoc.pdf
   = Package documentation
 9 /usr/local/texlive/2023/texmf-dist/doc/plain/metatex/mtpaper.pdf
   = Package documentation
10 /usr/local/texlive/2023/texmf-dist/doc/plain/mkpattern/mkpatter.pdf
   = Package documentation

Even if we give the inputnormalization document a negative score, the one that comes out on top is font-change.pdf, which also doesn't seem very useful in this case. I think it is realistic to have aliases for documents detailing plain TeX itself to the extent possible.

Incidentally, we have a similar problem with the query "latex", which is aliased to latex-doc-ptr.

texdoc/texdoc.cnf

Line 280 in cd6d6a8

alias latex = latex-doc-ptr

[wtsnjp]

Or we can prepare plain-doc-ptr if we want...

[muzimuzhi]

Or we can prepare plain-doc-ptr if we want...

docsurvey.pdf (https://ctan.org/pkg/docsurvey) has a section for plain tex docs. Right now it covers gentle, texbytopic, impatient, and other resources on the internet. I've just emailed the author of docsurvey to suggest to add tex-nutshell.

[kberry]

Incidentally, we have a similar problem with the query latex, which is aliased to `latex-doc-ptr`.

Right. And that is good. The aliasing of latex to latex-doc-ptr was another factor in my proposing an alias for plain. --thanks, karl.