path: root/macros/latex/contrib/ltxguidex/ltxguidex.tex

\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}|<<package>>|\texttt{\pipe} typesets as |<package>|.

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{<placeholder>}|\\
|\meta{<placeholder>}|
\end{desc}

Prints |<placeholder>| in italics within angle-brackets.

\ltx\ provides |\meta| as a synonym for |\m|.

\begin{LTXexample}
\m{placeholder}
\end{LTXexample}

\begin{desc}
|\arg{<argument>}|
|\oarg{<argument>}|
\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{<version>}|\\
|\NEWdescription{<version>}|
\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{<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{<<email>>}|
\end{desc}
\end{verbatim}
\end{example}

\begin{desc}
|\email{<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{<url>}|\qquad|\http{<url>}|
\end{desc}

Typesets |<url>| 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{<package>}| \\
|\ctanlogo|
\end{desc}

Typesets a package name with a link to |ctan.org/pkg/<package>|.

\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{<package>}|\\
|\ltxclass{<document class>}|\\
|\option{<option name>}|\\
|\filename{<filename>}|\\
|\extension{<file extension>}|
\end{desc}

Typesets a \LaTeX\ package, option, file extension, etc.\ in |\texttt|.

\begin{note}
	Unlike those defined in the \ctan{doctools} package, these commands
	don't add entries to the index.
\end{note}

\begin{LTXexample}
\extension{tex} files
\end{LTXexample}

\begin{desc}
|\begin{warning}...\end{warning}|\\
|\begin{note}...\end{note}|\\
|\begin{example}...\end{example}|\\
|\begin{bug}...\end{bug}|
\end{desc}

These environments typeset ``notices'' with a hanging indent. Original
definitions written by Javier Bezos for the \ctan{enumitem} documenation.
|\noticestyle| is executed before the marker text (``warning,'' ``note,''
etc.). New notice environments can be created with |\newnotice|.

\begin{bug}
	If the first content in a notice environment is vertical, the marker
	text is hidden. This can be avoided by starting the
	environment with |\leavevmode\\| or by adding some introductory
	material to the first line.

	This is actually a bug in the |\list| command that the notice
	environments use.
\end{bug}

\begin{example}
	Although this example is short, note that subsequent lines will
	be indented. These environments only vary by text.

\begin{LTXexample}
\begin{warning}
    Lorem ipsum\dots
\end{warning}
\end{LTXexample}
\end{example}

\begin{desc}
|\newnotice{<environment name>}{<marker text>}|
\end{desc}

Creates a new notice environment in the style of |warning|, |note|, and so
on. The marker text is automatically uppercased.

\begin{desc}
|\begin{LTXexample}[<options>]...\end{LTXexample}|
\end{desc}

Typesets \LaTeX\ code next to a listing of its source. Providing examples
makes your user's lives easier, and should be done as much as possible. The
|LTXexample| environment is provided by the \ctan{showexpl} package.
Excerpted from \ctan{showexpl}'s documentation as of v0.3o 2016/12/11, valid
options include:

\begin{keys}
	\key{attachfile}[\bool][false]

	If set to true the sourcecode will be attached to the
	\extension{pdf} file---presumed that the document is processed by
	|pdflatex|.

	\key{codefile}[\m{filename}][\bs jobname.tmp]
	Name of the (temporary) file that contains the code which will be
	formatted as source code. The default value is |\jobname.tmp|.

	\key{explpreset}[\m{key val list}][\{language=[LaTeX]TeX,\}]

	A |<key val list>| which serves for presetting the properties of the
	formatting of the source code, for values see the documentation of
	the \ctan{listings} package. The default value is
	empty.\footnote{\ltx\ redefines the default to perform syntax
	highlighting for \LaTeX, in addition to the general improvements
	made for all listings in the document.}

	\key{graphic}[\m{filename}]

	If present, includes and displays this file instead of the formatted
	code.

	\key{hsep}[\m{length}]
	Defines the horizontal distance between the source code and the
	formatted text.

	\key{justification}[\m{code}][\bs raggedright]
	Defines the justification of the formatted text: reasonable values
	are |\raggedleft|, |\raggedright|, |\centering|.

	\key{overhang}[\m{dimen}][0pt]
	Defines the amount by which the formatted text and the source code
	can overlap the print space. The default value is 0\,pt.

	\key{pos}[\m{\alternative{t,b,l,r,o,i}}][l]
	Defines the relative position of the formatted text relating to the
	source code. Allowed values are |t|, |b|, |l|, |r|, |o|, and |i| for
	top, bottom, left, right, outer, and inner. The last values give
	sense only for two-sided printing, where there are outer and inner
	margins of a page.

	\key{preset}[\m{code}]
	Any \TeX\ code executed before the sample code but not visible in
	the listings area.

	\key{rangeaccept}[\bool][false]
	If set to  true, one can define ranges of lines that will be
	excerpted from the source code.

	\key{rframe}[[\texttt{single}]][\textrm{\textit{(empty)}}]
	Defines the form of the frame around the formatted text. With a
	non-empty value (e.\,g. ``single'') a simple frame will be drawn. In
	the future more kinds of frames will be supported. The default value
	is empty (no frame).

	\key{varwidth}[\bool][false]
	If set to true, the formatted text is set with its ``natural'' width
	instead of a fixed width as given by the value of the option
	|width|.

	\key{vsep}[\m{dimen}]
	Defines the vertical distance between the source code and the
	formatted text.

	\key{wide}[\bool][false]
	If set to true, the source code and the formatted text overlap the
	print space and the margin area.

	\key{width}[\m{dimen}]
	Defines the width of the formatted text. The default value depends
	of the relative positions of the source code and the formatted text.

	\key{scaled}[[\m{scale factor}]]
	Without a value the formatted text will be scaled to fit the given
	width of the result area. With a number as value the formatted text
	will be scaled by this number.
\end{keys}

In addition to these options the kind of the result box (default: |\fbox|)
can be changed. For example:
\begin{latexcode}
\renewcommand\ResultBox{\fcolorbox{green}{lightgray}}
\setlength\ResultBoxSep{5mm}%  default: \fboxsep
\setlength\ResultBoxRule{2mm}% default: \fboxrule
\end{latexcode}

\begin{desc}
|\begin{packages}...\end{packages}|\\
|\begin{classes}...\end{classes}|\\
|\begin{options}...\end{options}|\\
\end{desc}

Frequently, package authors need to describe a series of options, packages,
or document classes. These environments wrap the |description| environment
and provide an |\item| which wraps a command like |\package|. In the
|packages| environment, |\item[listings]| translates to
|\item[\package{listings}]|.

\begin{LTXexample}
\begin{options}
    \item[foo] \dots
    \item[bar] \dots
\end{options}
\end{LTXexample}

\begin{desc}
|\begin{advise}...\end{advise}| $\equiv$\\
|\begin{faq}...\end{faq}|\\
|\Q|\qquad|\A|\qquad|\advisespace|
\end{desc}

Roughly copied from \ctan{listings}' internal \package{lstdoc} package,
these environments represent a list of questions and answers.

\begin{LTXexample}
\begin{faq}
\Q Lorem ipsum dolor sit amet?
\A Consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

\Q Ut enim ad minim veniam, quis nostrud?
\A Exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
\end{faq}
\end{LTXexample}

Within these environments, |\Q| and |\A| indicate a question and an answer;
they're defined to |\item| and |\advisespace|, respectively.

\begin{note}
	|faq| is an exact synonym for |advise|.

	The list label for the |advise| environment is |\labeladvise|.

	The font is set with |\advisestyle|.
\end{note}

\begin{desc}
|\alternative{<comma list>}|
\end{desc}

Prints a comma-separated list delimited by vertical bars. Space around
commas is not trimmed, and alternates are printed in
|\textup{\texttt{...}}|.

This environment is from \package{lstdoc}.

\begin{LTXexample}
\alternative{true,false}
\end{LTXexample}

\begin{desc}
|\begin{keys}...\end{keys}|\\
|\key[<options>]{<key name>}[<key value>][<default value>]|\\
|\bool|
\end{desc}

Describes keys. Within a |keys| environment, |\bool| indicates a true/false
value. This environment is a recreation of \package{lstdoc}'s |syntax|
environment with a more elegant interface.

|<options>| can include:

\begin{keys}
	\key{v}[\m{version}]
	The version a key was introduced.

	\begin{warning}
		This key is currently ignored.
	\end{warning}

	\key{default}[\m{default value}]
	An alias for the final argument; a default value if the key isn't
	given.

	\key{note}[\m{note}]
	A note set in the left margin; might note a group of features or
	something else.
\end{keys}

\begin{example}
	Note the use of |\bool|:
\begin{LTXexample}
\begin{keys}
  \key[note=addon]{key}
      [\m{value}][default]
  Lorem ipsum\dots

  \key{display}[\bool][true]
  Lorem ipsum\dots

  \key{foo}[\m{foo}]
  \key[v=1.3]{bar}
  Lorem ipsum\dots
\end{keys}
\end{LTXexample}
\end{example}

\begin{changelog}[author=Rebecca Turner]
\begin{version}[v=0.1.1, date=2019-04-15]
\added
	\item Renamed \cs{ltxguidex@noticestyle} to \cs{noticestyle} and committed
	it to the public \textsc{api}.
	\item The \cs{cs} and \cs{command} commands.
\end{version}
\end{changelog}

\end{document}