summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ltxguidex/ltxguidex.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/ltxguidex/ltxguidex.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/ltxguidex/ltxguidex.tex')
-rw-r--r--macros/latex/contrib/ltxguidex/ltxguidex.tex609
1 files changed, 609 insertions, 0 deletions
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}|<<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}