From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/ltxguidex/ltxguidex.tex | 609 +++++++++++++++++++++++++++ 1 file changed, 609 insertions(+) create mode 100644 macros/latex/contrib/ltxguidex/ltxguidex.tex (limited to 'macros/latex/contrib/ltxguidex/ltxguidex.tex') diff --git a/macros/latex/contrib/ltxguidex/ltxguidex.tex b/macros/latex/contrib/ltxguidex/ltxguidex.tex new file mode 100644 index 0000000000..3d5df6cff5 --- /dev/null +++ b/macros/latex/contrib/ltxguidex/ltxguidex.tex @@ -0,0 +1,609 @@ +\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{