summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ltxguidex/ltxguidex.tex
blob: 3d5df6cff54d1859dafcd3368bb4e2eab729b1fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
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}