\documentclass{ltxguidex} \usepackage{changelog} \usepackage{fontspec} \setmainfont{Tiempos Text} \usepackage{FiraSans} \usepackage{FiraMono} \def\labeladvise{→} \newcommand{\ltx}{\ltxclass{ltxguidex}} \newcommand{\ltxguide}{\ltxclass{ltxguide}} \title{Towards Better \LaTeX\ Documentation With the \ltx\ Document Class} \author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner@brandeis.edu}}} \date{2019/04/15 0.2.0} \begin{document} \maketitle \begin{abstract} The \ltx\ document class extends \ltxguide\ with a set of environments and commands that make writing beautiful \LaTeX\ documentation easier and more natural. \ltx\ is licensed under the \textsc{lppl} version 1.3c, or any later version at your choosing. This document is written with the \ltx\ document class. \end{abstract} \begin{note} This release of \ltx\ is an experimental public beta; it intends to demonstrate a hopeful new direction without committing to a stable public \textsc{api}. Although \ltx\ is now suitable for use in your own documentation, do not be surprised if future versions break your docs. \end{note} \begin{note} Browse the sources, contribute, or complain at \\ \https{github.com/9999years/ltxguidex} \end{note} \tableofcontents \vfill \pagebreak \section{The state of the docs} \LaTeX\ documentation is easy enough to write that --- in general --- nobody has bothered to package the improvements made to the \LaTeX documentation systems. If one examines the documentation for their favorite package, they'll likely find a few command definitions that make some aspect of documentation writing more ergonomic. In the case of complex packages like \ctan{listings} or --- in an extreme case --- \ctan{pgf}, it's commonplace to see packages define their own internal documentation packages containing hundreds-to-thousands of lines of documentation macros. This class repackages useful macros from various packages' documentation, often changing their form (e.g.\ the macro's interface) but keeping its style. I've tried to balance versatility against specialization (i.e.\ determining which features are the \textit{most} useful) as well as balancing short with descriptive names. \LaTeX\ documentation is enabled with two document classes and several packages. Document classes include: \begin{classes} \item[ltxdoc] Defines very little other than a few shorthands for documenting commands. Designed to be integrated with the \docstrip\ system, but I've seen plenty of \extension{dtx} files documented with \ltxguide. However, I haven't yet used \docstrip, so my experience here is limited. \item[ltxguide] Provides several ergonomic features absent in \ltxclass{ltxdoc}. However, \ltxguide\ is almost entirely undocumented, a fact which is partially mitigated by the fact that it's only about 150 lines long. \ltx\ is, as the name implies, based on \ltxguide. \end{classes} And supporting packages include: \begin{packages} \item[hypdoc] One of many, many packages by Heiko Oberdiek. \ctan{hypdoc} undertakes the ambitious task of patching the \ctan{doc} package in order to generate better indexes. In my experience, \ctan{hypdoc} is not compatible with \ltxguide; as such, it isn't loaded in \ltx. \item[doctools] Provides many useful secondary commands such as |\ltxclass|, |\package|, and so on. Many are duplicated here. \item[showexpl] Provides the |LTXexample| environment which typesets \LaTeX\ code and displays it in a listing side-by-side. \ctan{showexpl} provides the functionality of \ctan{listings}' |\lstsample| command and more. \ctan{showexpl} does, however, rely on the fairly hefty \ctan{listings} package. Compare to more ``plain'' \LaTeX\ documentation, \ltx\ documentation can be expected to compile somewhat slower. This author is of the opinion that the improvements are so numerous that the slow-down is worth it. \end{packages} \section{The \ltx\ document class} Although \ltx\ provides many useful commands, much of its utility is in its aesthetics. Much \LaTeX\ documentation is very ugly because producing beautiful documentation requires significantly more code than most package authors are interested in writing. This document is written with \ltx\ and one package loaded (the \ctan{bera} font family). Because \ltx\ is written with inherent beauty, it ends up being a bit heavier than its competitors; notably, it loads \ctan{xcolor}, \ctan{listings}, \ctan{graphicx}, and \ctan{calc} by default. \section{A note on typefaces} This document is set in \href{https://klim.co.nz/retail-fonts/tiempos-text/}{Tiempos Text} and \href{https://bboxtype.com/typefaces/FiraSans/}{Fira Sans} (available on \textsc{ctan} as \ctan{fira}). For your own documents, I would recommend \ctan{bera} or \ctan{plex}, although neither has small caps, which I consider essential. When deciding on a serif font for \LaTeX\ documentation, I would recommend picking one with a tall x-height, as larger overall glyphs makes documents easier to read on small screens (nobody's going to be printing out your documentation). This will rule out most old-style serif typefaces, such as Garamond and Calson. \section{Commands provided by \ltxguide} In \ltxguide, pipe characters (\texttt{\pipe}) mark verbatim text. However, between two pipes, the angle brackets |<<| and |>>| typeset as pretty angle brackets with regular italics between them; therefore, \texttt{\pipe}|<>|\texttt{\pipe} typesets as ||. To write literal angle brackets, simply double the characters; \texttt{\pipe}|<<<<|\texttt{\pipe} will render as |<<| and \texttt{\pipe}|>>>>|\texttt{\pipe} will render as |>>|. \begin{desc} |\pipe|\\ |\bs| \end{desc} To write literal pipe characters, use the |\pipe| command. To write a literal backslash, use the |\bs| command. \begin{LTXexample} \pipe \\ \texttt{\pipe} \\ \textit{\pipe} \\ \textbf{\texttt{\pipe}} \\ \bs \\ \texttt{\bs} \\ \textit{\bs} \\ \textbf{\texttt{\bs}} \end{LTXexample} \ltxguide\ uses \ctan{shortvrb} to activate pipes as a synonym for short-verbatim material. There are some small conflicts with \ltx's use of the \ctan{listings} package (in particular, pipes are silently gobbled from |lstlistings| environments, although they work normally within |verbatim|), which will hopefully be resolved with a coming change to \package{listings}; this simply depends on how quickly Jobst Hoffmann emails me back. \ltxguide\ also provides the |decl| environment that powers the |desc| environment. \begin{desc} |\m{}|\\ |\meta{}| \end{desc} Prints || in italics within angle-brackets. \ltx\ provides |\meta| as a synonym for |\m|. \begin{LTXexample} \m{placeholder} \end{LTXexample} \begin{desc} |\arg{}| |\oarg{}| \end{desc} Shorthands for mandatory and optional arguments. \begin{LTXexample} \arg{foo}\oarg{bar} \end{LTXexample} \begin{desc} \begin{tabular}{@{}ll@{}} |\NFSS| & \NFSS\\ |\AmS| & \AmS\\ |\AmSLaTeX| & \AmSLaTeX\\ |\babel| & \babel\\ |\SLiTeX| & \SLiTeX\\ |\ctanlogo| & \ctanlogo\\ \end{tabular} \end{desc} Various logos. \begin{note} \ltxguide\ actually defines the \ctanlogo\ logo as |\ctan|, but this class uses |\ctan| to refer to a package, so the \ctanlogo\ logo is typeset with |\ctanlogo|. \end{note} \begin{desc} \begin{tabular}{@{}ll@{}} |\clsguide| & \clsguide \\ |\usrguide| & \usrguide \\ |\fntguide| & \fntguide \\ |\cfgguide| & \cfgguide \\ |\cyrguide| & \cyrguide \\ |\modguide| & \modguide \\ |\sourcecode| & \sourcecode \\ |\LaTeXbook| & \LaTeXbook \\ |\LaTeXcomp| & \LaTeXcomp \\ |\LaTeXGcomp| & \LaTeXGcomp \\ |\LaTeXWcomp| & \LaTeXWcomp \\ \end{tabular} \end{desc} The names of various documents, presumably intended only for the original \ltxguide\ document. \begin{desc} |\eg|\\ |\ie| \end{desc} Shortcuts for ``e.g.,''\ and ``i.e.,''\ followed by a non-breaking space. \begin{LTXexample} \ie the document class\dots\\ \eg the package\dots \end{LTXexample} \begin{desc} |\NEWfeature{}|\\ |\NEWdescription{}| \end{desc} \NEWfeature{1.0.0} \NEWdescription{1.0.0} Typeset their arguments in a |\marginpar|. This paragraph is prepended by |\NEWfeature{1.0.0}| |\NEWdescription{1.0.0}|. \begin{desc} |\URL{}| \end{desc} Typesets its argument in |\texttt|. Obsolete given that \ltx\ loads \ctan{hyperref}. \section{New commands} \ltx\ provides several new commands for convenience. \begin{desc} |\begin{desc}...\end{desc}| \end{desc} Describes a command or environment, setting it out into the margin and surrounding it with a frame. Originally written by Javier Bezos for the \ctan{enumitem} documenation. \begin{example} Unfortunately, a side-by-side listing doesn't seem to be possible here because pipes seem to be gobbled by the \package{listings} package (a side-effect of loading both \ctan{listings} and \ctan{shortvrb}, perhaps). However, here's how the |\email| command is described in this document: \begin{verbatim} \begin{desc} |\email{<>}| \end{desc} \end{verbatim} \end{example} \begin{desc} |\email{}| \end{desc} Typesets an email address with a |mailto:| link. \begin{example} Emails, along with other hyperlinks, are colored |magenta|, although \ltx's default magenta is a bit closer to purple. \begin{LTXexample} \email{rebeccaturner@brandeis.edu} \end{LTXexample} \end{example} \begin{desc} |\https{}|\qquad|\http{}| \end{desc} Typesets || with |https://| or |http://| prepended to the link address; this makes links display a bit prettier than |\url| might. \begin{example} The following two listings are equivalent: \begin{LTXexample} \https{ctan.org} \end{LTXexample} \begin{LTXexample} \href{https://ctan.org}{ctan.org} \end{LTXexample} \end{example} \begin{desc} |\ctan{}| \\ |\ctanlogo| \end{desc} Typesets a package name with a link to |ctan.org/pkg/|. \begin{warning} \ltx's definition of |\ctan| differs from \ltxguide's, which simply typesets ``\ctanlogo'' in small-caps. The \ctanlogo\ logo is typeset with |\ctanlogo|. \end{warning} \begin{LTXexample} the \ctan{listings} package\dots \end{LTXexample} \begin{desc} |\package{}|\\ |\ltxclass{}|\\ |\option{