2

I want to use some packages in latex, then I find the manual for that package. However I find all these manual are purely codes and explanation without any explicit examples and shown results. I'm not a computer scientist. It's fairly boring and inefficient for me to read all plain texts to understand how to use this package. Is there any place where I can find the manual for every package for amateurs like me? I want this manual/note(certainly not necessarily written by packages' authors) has such properties:

  1. Not too sketchy like just choosing few easy examples to introduce the framework. I want it's comprehensive and can tell me all details of every function or method or parameter in that package.

  2. The most important for me is that every function/method/parameter should have explicit examples and shown results. Therefore I can fast explore the shown results and aha, this is what I want it looks like.

PS: I certainly understand that LaTeX is not a paid software. The authors of packages have right to write anyway as they like. I wonder whether there are some good instructors who digest the original dry manual and feed amateurs who don't just want to scratch the surface by a friendly way. A good example of what I want is like document center of Wolfram Mathematica.

  • 9
    Welcome to TeX.SE! I think you are generalizing too much. Have you already seen the TikZ-PGF manual? It's exactly the opposite of what you describe. I think that the answer to your question is: no, there isn't, because the manual is written (usually) by the package author and it's up to them to choose what to show. Some packages have nice illustrative examples and some don't. – Phelype Oleinik Feb 25 at 23:44
  • @PhelypeOleinik I certainly understand. I mean whether there are comprehensive notes written by some instructors who are good at teaching. Not as dry as original manual written by author/ – maplemaple Feb 25 at 23:48
  • 2
    I can't give a 100% sure “no there isn't”, but it's as close to that as it can be. Writing a package manual is not that easy and requires quite a bit of time and patience, and most package authors write packages/documentation as a hobby, not as a profession. There might be packages which have what you ask, but most don't have simply because there are thousands of packages out there, so you can't expect someone to be willing to do that. However, if you are asking for a specific package, then someone might know a “better than the manual” document out there to point you to. – Phelype Oleinik Feb 25 at 23:54
  • 1
    Completely agree. Most Latex packages documentation are not useful to learn how to use the package from because they do not contain useful examples. – Nasser Feb 26 at 2:20
  • 2
    There are several books which attempt to address this need quite successfully, although obviously they are limited in scope and current practice. Three I have recommended are The LaTeX Companion", Kopka & Daly's *Guide to LaTeX, and George Grätzer's More Math into LaTeX. Unfortunately, they're not free. – barbara beeton Feb 26 at 14:05
4

No, such a site doesn't exist, and nobody's going to create it for you just because you find the manual boring.

Mathematica is a proprietary application and they're able to control how their packages are documented. Python is open source, but has a strong community ethic where they pretty much all agree that “there should be one—and preferably only one—way to do it.” So good documentation is part of the culture. LaTeX is neither of those things.

I agree with the commenters that some package documentation is quite good. tikz and pgfplots are among my favorites. And most documentation isn't bad; it just may not spell out every single possible thing you might want to do with it.

But if you are looking for a vast resource of answered questions for various LaTeX (and ConTeXt, and core TeX) use cases, you may have already found it. Questions on TeX.SE are tagged by packages used so you can browse and search for lots of examples. Pages on TeX.SE are highly findable. Usually I just google "latex (thing I want to do)" and the top result is usually a page from this site. And if you don't find what you want—ask!

  • 3
    I'd add tcolorbox to the list. – Sigur Feb 26 at 0:29
  • 1
    I agree with most of this. It might be worth pointing out, though, that LaTeX also generally has a culture that encourages documentation (ctan.org/help/upload-pkg, tug.org/texlive/pkgcontrib.html), but there are little to no standards there and some of the established practices were more concerned with documenting the source rather than giving usage examples. – moewe Feb 26 at 8:28
2

I'm sorry but I think that you are being too ambitious in your request. However the authors of the LaTeX Companion series (LaTeX Companion, LaTeX Graphics Companion and LaTeX Web Companion, all published by Addison Wesley) have gone a long way to meeting your request. As for individual packages/classes it is up to the developers/authors to provide the documentation they think is important. I guess that in most cases they, and certainly I, assumed that the readers would have a certain knowledge of LaTeX and would not have to repeat any basic elements.

I was the original developer of the memoir class (> texdoc memoir) to read the manual which consists of about 540 pages. Included in these is a 40 page index of all the macros within the class, all of which are described to a greater or lesser extent in the body of the manual. Examples of the results from using the main ones are given. Examples of every use of every macro in the class would, I estimate, triple the size of the manual. Who would read that? And I certainly would not write it.

As you have an idea of what you want to see would you be willing to write amateur-level documentation of the packages that you have come to understand and submit them to CTAN for general distribution?

GOM

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.