From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
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}|<<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}
-- 
cgit v1.2.3

