Helping with TeX documentation projects

This page gives details for a few documentation projects that would be great to pursue, in no particular order. For other projects looking for volunteers, both documentation and code, see the main how to help page.

If you're looking for help with using TeX, rather than ways to contribute, please see the getting started with TeX page.

If you're interested, please email webmaster@tug.org, and thanks.

Best practice LaTeX for the web

Description: LaTeX has traditionally been geared towards generating print documents, nowadays generating PDF output. There is now more and more need to develop documentation in HTML form as well, and with the widespread adoption of MathML and alternative rendering technologies such as MathJax, there is little technical reason that LaTeX documents can not produce first-class HTML output as well as PDF output. In fact, there are a number of actively developed projects which allow this, including TeX4ht, LaTeXML, lwarp, HEVEA, and others.

For a newcomer, this creates a problem — each tool is suited toward different workflows and it is often not clear which would be the best to choose for a given project. As these are quite complex tools, it is also sometimes hard to get started and to know the limitations of each technology. This project proposes to write a comprehensive user guide to writing HTML documents using LaTeX workflows, comparing and contrasting the currently available technologies.

Related material:

Bib(La)TeX style catalogue

Description: It would be helpful to have a visual catalog of the many BibTeX styles and BibLaTeX styles, along the lines of what the LaTeX Font Catalogue does for fonts.

TikZ tutorials for programmatic drawing

Description: The PGF/TikZ environment for programmatic drawing in TeX documents has become the de facto standard for including high-quality visual elements to a (La)TeX document. Its interface has evolved over a number of years and achieves a remarkable level of clarity given it is built on top of the TeX macro environment. PGF/TikZ and related add-ons can draw anything from flowcharts to 2D and 3D graphics to entire graphs (replacing, e.g., matplotlib for generating figures, with the benefit of tight coupling between graph style and document design in terms of fonts and colours).

The vast capabilities and improvements to its interface over time have lead to a noticeable gap in the documentation. The PGF/TikZ documentation is formiddable at 1289 pages, and while it provides some tutorial elements it is more of a reference document than a user guide. There are also a large number of example graphics online through the TeXample website, but these are often written using older or ad hoc idioms and are often not good examples of best practice. For this project we propose that a set of worked examples are developed that showcase TikZ’s range and can be used as reference examples to build from for new users. This project may also lead to improvements in the core PGF/TikZ documentation.

Related material:

LaTeX3 and LuaTeX programming tutorials

Description: In the early 2010s the expl3 programming layer started gaining significant traction for LaTeX programming. expl3 was a re-think of how TeX macro programming could be performed with rigorous syntax and robust data structures. Around the same time, the LuaTeX project was released, which allows TeX documents to be programmed using the Lua programming language. These two approaches are complementary and in some sense provide a transition from the legacy code of LaTeX2e into a future version of LaTeX that has clean interfaces for the document author, class designer, and code writer.

While expl3 and LuaTeX are both extensively described with reference documentation, neither have comprehensive user guides or tutorials for teaching a newcomer to TeX how to adopt these new best practices. This project would create a suite of documents for doing so.

Related material:

LaTeX2e reference documentation (https://latexref.xyz)

Description: LaTeX2e, the version of LaTeX used worldwide since 1993 by myriad mathematicians, scientists, engineers, computer scientists, linguists, and so on, lacks comprehensive reference documentation. An ambitious project has been started at https://latexref.xyz that catalogues and documents all non-private LaTeX2e commands. Further improvements to that document are necessary, including expanding the scope of the documentation to private/internal commands as well as general programming interfaces. As part of this effort, the documentation provided via the literate programming implementation of LaTeX2e could be thoroughly updated and re-written to harmonise with this project. In parallel with this project the interface to the documentation could be thoroughly revamped to exploit modern web technologies, but this would not fall under the direct responsibility of the technical writer.

Related material:


$Date: 2019/08/21 21:30:18 $;
TUG home page; webmaster; facebook (group), twitter;   (via DuckDuckGo)