diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-14 22:07:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-14 22:07:57 +0000 |
commit | 2464f44948bb379ec3bb813d9fa0c937dcb4e6a8 (patch) | |
tree | 2116c31c02792206e268c6271d45ff8819f60d87 /Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex | |
parent | 6950156f10651c7d5f976001ab97f0e8e5bcffb4 (diff) |
ltxguidex (14jan19)
git-svn-id: svn://tug.org/texlive/trunk@49705 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex | 600 |
1 files changed, 600 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex b/Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex new file mode 100644 index 00000000000..cf2795589d8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/ltxguidex/ltxguidex.tex @@ -0,0 +1,600 @@ +\documentclass{ltxguidex} +\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/01/13 v0.1.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. +|\ltxguidex@noticestyle| is executed before the marker text (``warning,'' +``note,'' etc.) in a separate group. 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} + +\end{document} |