As a board member of the TeX Users Group, earlier this month I was investigating the Google Season of Docs scheme to establish whether it would be feasible for TUG to participate in 2019. The idea of these scheme is to bring in technical writers looking for experience in real-world ‘gaps’ in open source software documentation. The activities can range from frameworks, to tutorials, to reference documentation.

The TeX ecosystem is somewhat unique in the open source software world in that its software is often highly documented in a ‘soft’ literate programming approach using LaTeX’s DocStrip syntax or variants thereof. This documentation is distributed in PDF form and is one of the main reasons that a ‘complete’ TeX Live distribution is multi-gigabytes in size (the other reason being fonts).

However, just because code in TeX Live tends to come with PDF documentation doesn’t mean there aren’t ample opportunities for more and better documentation. The GSOD scheme looks fantastic but time ended up running short for our proposals; most importantly, we didn’t want to propose projects for which we didn’t have confidence we could provide adequate support.

Despite not progressing with the scheme this year, if it returns again in 2020 I’m more confident we will be in a better place to make a strong set of proposals. For reference I’ve listed what would have been our intended entries into our Google Season of Docs 2019 submission, had it gone ahead.

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:

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: