0

This is basically Where is the documentation?, but let me repeat it for a bit and then suggest an idea... skip past the line to get there immediately

After thinking about this for a while, I reached the conclusion that a big part making (La)TeX complicated for me is the documentation (or my approach on how to find it).

Yes, TeX is incredibly old and has many extensions and flavours and competing bad practices floating around, but I speculate that would be half as bad if it was intuitive to reach the documentation. So let us observe how I approach that and what we might learn from it:

  • I realise I need something I don't know how to achieve or a macro doesn't work as I understood it
  • I google what I want or the command
  • I expect some documentation site to show up in the first page of results, but there are at most StackExchange or similar QA pages, no formal docs listing all options etc.

Answers to the post mentioned originally ftp://ftp.dante.de/tex-archive/help/Catalogue/alpha.html (which doesn't seem to work for me, chromium tries to open firefox which doesn't know what to do with it either), https://www.ctan.org/tex-archive/info/LatexHelpBook or good old texdoc <package name> (which tells me texdoc error: No texlive.tlpdb nor shipped tlpdb data found., maybe I have to install the docs separately?) — Anyway, not userfriendly enough with todays conventions, in my opinion.

So, what is the argument against creating a documentation hub in the style of Read the Docs or whatever finds consent, where the core and all known (or the most used) packages can be read up on, with all macros they introduce and their options and implications? Ideally, with added cross references as well. I imagine it on https://www.latex-project.org/ or directly linked and promoted from there.

I can only think of the question of a strategy regarding future versions. If packages are added without their authors acknowledging and endorsing it, they would not submit their updated documentation. Having a team manually chase those is not a future proof strategy for sure, but I think only adding the most popular packages at first and relying on the (hopefully) increasing popularity of the documentation to drive authors to submit their docs from then on could work well.

So, what are your thoughts on this? Is this completely unnecessary? Is such a project already underway? If so, it hasn't reached my search results yet.

Edit: Existing project in that direction that was brought to my attention: https://texdoc.net – finds documentation resources for package names, does not allow searching for macro names. I suggested this as an issue

Peter Nerlich
  • 195
  • 2
    Almost all packages of distributions have their documentation in pdf format. – Bernard Aug 19 '21 at 11:13
  • 5
    texdoc.net ?.... – David Carlisle Aug 19 '21 at 11:13
  • 2
    you seem to have a local installation error with texdoc, but hard to diagnose that given the information provided. Almost evry one of the thousands of available packages has documentation available via texdoc locally or via texdoc.net online – David Carlisle Aug 19 '21 at 11:15
  • @DavidCarlisle texdoc.net looks very closely like what I mean! Unfortunately, the focus is on finding the documentation for a known package, with no way to lookup a macro name. I see the project is also quite young, and SEO is already created as a tracked issue. – Peter Nerlich Aug 19 '21 at 11:30
  • texdoc.net is newish but is essentially the same as the older texdoc.org (which now redirects to .net) but for most users I would guess texdoc (or an editor menu that runs that) is the first call and provides more documentation than you could possibly ever read. – David Carlisle Aug 19 '21 at 11:52
  • @DavidCarlisle The other way around, org is newer than net ;) – TeXnician Aug 19 '21 at 16:39
  • The Island of TeX (creators of texdoc.org) are open for discussions. You may simply open feature requests there to improve the known documentation site further. – TeXnician Aug 19 '21 at 16:39
  • @TeXnician ah details:-) – David Carlisle Aug 19 '21 at 16:42
  • 3
    (La)TeX is supported by volunteers who do it in their spare time. I hope that you are volunteering to create a documentation hub. If not, who do you expect to do it when the vast majority of users are satisfied with texdoc and the published books, etc. ? – Peter Wilson Aug 19 '21 at 17:11
  • @PeterWilson Actually, yes, I'd at least have a go at it (though I wouldn't expect myself to be very successful). But since I don't feel up to date with the (La)TeX community by any means, what I wanted to achieve with this post was to see how it would react to that idea and whether there were actually similar projects that just didn't climb the search results. So I got what I wanted: I now know texdoc.net exists and can direct any efforts I might make in the future towards that project. But even if nothing of that happened, there could have been a tiny chance someone got inspired to make it. – Peter Nerlich Aug 20 '21 at 20:48
  • 1
    There are a few questions here about finding a package given a command, perhaps https://tex.stackexchange.com/q/4327/86 is the place to start. – Andrew Stacey Aug 20 '21 at 21:13
  • 1
    Also: How to find the documentation for a package? – Alan Munn Aug 20 '21 at 21:51

0 Answers0