summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/democodetools/doc/democodetools.tex
blob: cbb47a0f6022d03b3a72d1172a596147cfff4a57 (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
%%%==============================================================================
%% Copyright 2022 by Alceu Frigeri
%%
%% This work may be distributed and/or modified under the conditions of
%%
%% * The [LaTeX Project Public License](http://www.latex-project.org/lppl.txt),
%%   version 1.3c (or later), and/or
%% * The [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.html),
%%   version 3 (or later)
%%
%% This work has the LPPL maintenance status *maintained*.
%%
%% The Current Maintainer of this work is Alceu Frigeri
%%
%% This is version 1.0.1beta (2022/09/06)
%%
%% The list of files that compose this work can be find in the README.md file at
%% https://ctan.org/pkg/democodetools
%%
%%%==============================================================================
\makeatletter
\def\tc@tmp@packname{democodetoolsdoc}
\def\tc@tmp@altpackname{democodetoolsdoc}
\def\tc@tmp@packdesc{Demo Code Tools Documentantion}
\def\tc@tmp@packdate{2022/09/06}
\def\tc@tmp@packversion{1.0.1beta}
\let\@exp\expandafter
\@exp\edef\csname\tc@tmp@altpackname version\endcsname{\tc@tmp@packversion}
\makeatother

\documentclass[dctools,english]{ufrgscca}
\usepackage{democodetools}

\dcTitle{The democodetools and democodelisting Packages - Version \democodetoolsversion}
\dcAuthor{Alceu Frigeri}
\dcDate{September 2022}

\begin{document}

\dcMakeTitle

\begin{dcAbstract}
This is `yet another doc/docx/doc3' package. It is designed to be `as class independent as possible', meaning: it makes no assumption about page layout (besides `having a marginpar') or underline macros. Furthermore, it's assumed that \Macro{\maketitle}{} and the \Key{abstract} environment were modified by the underline class, so alternatives (based on the article class) are provided. The main idea is to be able to document  a package/class loading it first and then this, so that it is possible not only to document the `syntax' but also to show the end result `as is' when using that other specific class/package.

\end{dcAbstract}

\tableofcontents

\section{Introduction}
The packages/classes doc/docx/doc3 (and for that matter doctools) where designed to be used with dtx files, which is handy for package developers, as long as one is fine with the `default article' format (which is true most of the time). This came to be from the willingness of having the `new look and feel' used in doc3, but, instead of having to rely on a standard class, being able to use any class as the base one, which allows to `demonstrate the documented commands with the final layout'.\\

\Pack{democodelisting} defines a few macros to display and demonstrate \LaTeX~ code verbatim (using \Pack{listings} and \Pack{scontents}), whilst \Pack{democodetools} defines a series of macros to display/enumerate macros and environments (somewhat resembling the \Pack{doc3} style).\\
\subsection{Current Version}
This doc regards to \Pack{democodelisting} version \democodelistingversion~ and \Pack{democodetools} version \democodetoolsversion. Those two packages are 'usable' but they haven't been thoroughly tested, nor should  anyone consider them stable (they might be considered more or less stable but more due the 'maintainer'  lack of time than anything else. Use it at your own risk.)

\section{democodelisting Package}

It requires two packages: \Pack{listings} and \Pack{scontents}\\
Defines an environment: \Env{stcode} and\\
 4 commands: \Macro{\DemoCode}{}, \Macro{\DisplayCode}{},  \Macro{\TabbedDisplayCode}{} and \Macro{\setdclisting}{}.

\subsection{In Memory Code Storage}
Thanks to \Pack{scontents} (\Pack{expl3} based) it's possible to store \LaTeX~ code snippets in a \Pack{expl3} key.

\begin{Envs}{stcode}
	\begin{Syntax}%
		\Macro{\begin{stcode}}[keys]{} \Macro{\end{stcode}}{}
	\end{Syntax}
This environment is an alias to \Env{scontents} environment (from \Pack{scontents} package), all \Pack{scontents} keys are valid, with an additional one: \Key{st} which is an alias to the \Key{store-env} key.
The environment body is stored verbatim in the \Key{st} named key.
\end{Envs}

\subsection{Code Display/Demo}
\begin{Macros}{\DisplayCode,\DemoCode,\TabbedDemoCode}
	\begin{Syntax}%
		\Macro{\DisplayCode}[dclisting-keys]{st-name}
		\Macro{\DemoCode}[dclisting-keys]{st-name}
		\Macro{\TabbedDemoCode}[dclisting-keys]{st-name}
	\end{Syntax}
\end{Macros}
\Macro{\DisplayCode}{} just typesets \Arg{st-name} (the key-name created with \Env{stcode}), in verbatim mode with syntax highlight.\\
\Macro{\DemoCode}{} first typesets \Arg{st-name}, as above, then it \emph{executes} said code.
Finally \Macro{\TabbedDemoCode}{} does the same, but typesetting it, and executed code, side by side. N.B. Both typeset  and executed code are placed inside a \Env{minipage} so that, when \emph{executing} the code, one can have, for instance, 'normal' paragraph indentation.\\
For Example:

\begin{stcode}[st=demostcode]
	\begin{stcode}[st=stmeta]
		Some \LaTeX~coding, for example: \ldots.
\end{stcode}
This will just typesets \Key{stmeta}:

 \DisplayCode{stmeta}

and this will demonstrate it, side by side with source code:

\TabbedDemoCode[numbers=left,codeprefix={inner code},resultprefix={inner result}]{stmeta}
\end{stcode}

\DemoCode[emph={DisplayCode,TabbedDemoCode},keywd2={stcode}]{demostcode}

\begin{Macros}{\setdclisting}
	\begin{Syntax}%
		\Macro{\setdclisting}{dclisting-keys}
	\end{Syntax}
Instead of setting/defining \Meta{dclisting-keys} per \Macro{\Demo}{}/\Macro{\Display}{} call, one can set those \emph{globally}, better said, \emph{in the called context group} .\\
N.B.: All \Macro{\Display}{}/\Macro{\Demo}{} commands create a local group (\Macro{\begingroup}{}) in which the \Meta{dclisting-keys} are defined, and discarded once said local group is closed. \Macro{\setdclisting}{} defines those keys in the \emph{current} context/group (\Macro{\def}{}, \Macro{\edef}{})
\end{Macros}

\subsubsection{\Meta{dclisting-keys}}
Using a \Key{key}\,=\Value{value} syntax, one can fine tune \Pack{listings} syntax highlight.
\begin{Args}
\DescribeArg{dclisting-keys}
\begin{Syntax} %
	\Keylst{settexcs,settexcs2,settexcs3}
	\Keylst{texcs,texcs2,texcs3}
	\Keylst{texcsstyle,texcs2style,texcs3style}
\end{Syntax}Those define sets of \LaTeX~commands (csnames), the \Key{set} variants initialize/redefine those sets (an empty list, clears the set), while the others extend those sets. The \Key{style} ones redefines the command display style (an empty \Meta{par} resets the style to it's default).\\

\begin{Syntax}	%
	\Keylst{setkeywd,setkeywd2,setkeywd3}
	\Keylst{keywd,keywd2,keywd3}
	\Keylst{keywdstyle,keywd2style,keywd3style}
\end{Syntax}
Same for other \emph{keywords} sets.\\

\begin{Syntax}	%
	\Keylst{setemph,setemph2,setemph3}
	\Keylst{emph,emph2,emph3}
	\Keylst{emphstyle,emph2style,emph3style}
\end{Syntax}
for some extra emphasis sets.\\

\begin{Syntax} %
	\Keylst{numbers,numberstyle}
\end{Syntax}
\Key{numbers} possible values are \Value{none} (default) and \Value{left} (to add tinny numbers to the left of the listing). With \Key{numberstyle} one can redefine the numbering style.\\

\begin{Syntax} %
	\Keylst{stringstyle,commentstyle}
\end{Syntax}
to redefine \Key{strings} and \Key{comments} formatting style.\\

\begin{Syntax} %
	\Key{bckgndcolor}
\end{Syntax}
to change the listing background's color.\\

\begin{Syntax} %
	\Keylst{codeprefix,resultprefix}
\end{Syntax}
those set the \Key{codeprefix} (default: \LaTeX~Code:) and \Key{resultprefix} (default: \LaTeX~Result:)
\end{Args}

\section{democodetools Package}




\subsection{Environments}
\begin{Envs}{Macros,Envs}
\begin{Syntax}%
\Macro{\begin{Macros}}{macrolist}
\Macro{\begin{Envs}}{envlist}
\end{Syntax}
Those are the two main environments to describe \Env{Macros} and \Env{Environments}. Both typeset \Arg{macrolist} (csv list) or \Arg{envlist} (csv list) in the margin. N.B. Each element of the list gets \Macro{\detokenize}{}
\end{Envs}

\begin{Envs}{Syntax}
\begin{Syntax}%
\Macro{\begin{Syntax}}{}
\end{Syntax}
The \Env{Syntax} environment sets the fontsize and activates \Macro{\obeylines}{}, so one can list macros/cmds/keys use, one per line.

\begin{stcode}[st=demoD]
\begin{Envs}{Macros,Envs}
\begin{Syntax}%
\Macro{\begin{Macros}}{macrolist}
\Macro{\begin{Envs}}{envlist}
\end{Syntax}
Those are the two main ...
\end{Envs}
\end{stcode}
\DisplayCode{demoD}

\end{Envs}


\begin{Envs}{Args,Keys,Values,Options}
\begin{Syntax}%
\Macro{\begin{Args}}{}
\Macro{\begin{Args+}}{}
\Macro{\begin{Keys}}{}
\Macro{\begin{Keys+}}{}
\Macro{\begin{Values}}{}
\Macro{\begin{Values+}}{}
\Macro{\begin{Options}}{}
\Macro{\begin{Options+}}{}
\end{Syntax}

Those environments are all the same, starting a dedicated \emph{description list}. Together with the many \Macro{\Description...}{} commands, one can list all \Keylst{Options, Args, Keys, Values} as needed. The \Key{+} form are meant to be used with the \Macro{\Description...+}{} forms, for \emph{in text} lists. The non \Key{+} form are meant to have the many \emph{'descriptors'} in the \emph{margin par}.
\end{Envs}

\subsection{Describe Commands}
\begin{Macros}{\DescribeMacro}
\begin{Syntax}%
\Macro!{\DescribeMacro}<*!+>{\marg{csname}\oarg{oarglist}\marg{marglist}}
\end{Syntax}
\begin{Args+}
\DescribeKey+{*} typesets the macro name in bold face.
\DescribeKey+{!} \Arg{marglist} is treated as an expandable code, 'as is'.
\DescribeKey+{+} the macro name is typeseted in text.
\DescribeArg+{csname} macro name (\Macro{\detokenize}{})
\DescribeArg+{oarglist} csv list of optional args.
\DescribeArg+{marglist} csv list of mandatory args.
\end{Args+}
\end{Macros}

\begin{Macros}{\DescribeArg,\DescribeKey,\DescribeValue,\DescribeOption,\DescribePackage,}
\begin{Syntax}%
\Macro{\DescribeArg}<*+>[type]{arg}
\Macro{\DescribeKey}<*+>[type]{arg}
\Macro{\DescribeValue}<*+>[type]{arg}
\Macro{\DescribeOption}<*+>[type]{arg}
\Macro{\DescribePackage}<*+>[type]{arg}
\end{Syntax}
\begin{Args+}
\DescribeKey+{*} typesets it in bold face.
\DescribeKey+{+} typesets in text (not in marginpar)
\DescribeArg+{type} key/arg/... format
\DescribeArg+{arg} key/arg/... name.
\end{Args+}
\end{Macros}


\subsection{Macros Typeset}
\begin{Macros}{\Macro}
	\begin{Syntax}%
		\Macro!{\Macro}{\marg{csname}\xarg{embl}\oarg{olist}\marg{mlist}}
		\Macro!{\Macro}<!>{\marg{csname}\xarg{embl}\marg{par.desc.}}
	\end{Syntax}
	When describing a macro \Arg{csname} (Command Sequence, csname) the \Arg{olist} and \Arg{mlist} are comma separated lists (csv) of optional and mandatory arguments. \Arg{embl} are optional, single char,  'embellishment' tokens, like {\bfseries * ! +}. Finally, in the {\bfseries !} form, the \Arg{par.desc.} is any text representing the macro parameter list (for non regular, non usual, cases).

	\begin{stcode}[st=demoB]
		\Macro
		{\Macro}<*!>[opt1,opt2]{arg3}
		\Macro!
		{\Macro}<!>{\xarg{embl}\marg{par.desc.}}
\end{stcode}
	\TabbedDemoCode{demoB}
\end{Macros}

\subsection{Args  Typeset}
\begin{Macros}{\oarg,\marg,\parg,\xarg,\Arg,\Meta}
	\begin{Syntax}%
		\Macro{\oarg}[type]{arg}
		\Macro{\marg}[type]{arg}
		\Macro{\parg}[type]{arg}
		\Macro{\xarg}[type]{arg}
		\Macro{\Arg}[type]{arg}
		\Macro{\Meta}{arg}
	\end{Syntax}
	Those are meant to typeset the diverse kinds of 'command's arguments' (mandatory, optional, parenthesis . . .). \Macro{\Meta{arg}}{} typesets \emph{arg} as \Meta{arg}.
	\begin{Args}
		\DescribeArg{type} defaults to \Value{Meta} (it's the csname of any valid formatting command, like Meta, textbf, etc.)
		\DescribeArg{arg} the argument name itself.
	\end{Args}
	\begin{stcode}[st=demoA]
		\oarg{fam}
		\parg{xtra}
		\marg[textbf]{text}
		\xarg{x-text}
\end{stcode}
	\TabbedDemoCode{demoA}
\end{Macros}

\subsection{Keys  Typeset}
\begin{Macros}{\Key,\Keylst,\KeyUse}
	\begin{Syntax}%
		\Macro{\Key}[pre]{key}
		\Macro{\Keylst}[default]{keylst}
		\Macro{\KeyUse}{key}{value}
	\end{Syntax}
	To typeset a \Arg{Key} or \Arg{keylst} (csv list). \Arg{pre} is just prepended to \Arg{key} whilst \Arg{default} is the default key value. \Macro{\KeyUse}{} is just a short-cut for a, possible, common construction.

	\begin{stcode}[st=demoC]
		\Key{Akey}

		\Keylst[Bkey]{Akey,Bkey}

		\KeyUse{keyA}{arg}
\end{stcode}
	\TabbedDemoCode{demoC}

\end{Macros}

\begin{Macros}{\Env,\Pack,\Value}
	\begin{Syntax}%
		\Macro{\Env}[pre]{key}
		\Macro{\Pack}[pre]{key}
		\Macro{\Value}[pre]{key}
	\end{Syntax}
	Similar to \Macro{\Key}{} above, they will typeset a \Arg{Key}. \Arg{pre} is just prepended to \Arg{key} whilst \Arg{default} is the default key value.


\end{Macros}


\subsection{Others}
\begin{Macros}{\MetaFmt}
	\begin{Syntax}%
		\Macro{\MetaFmt}<*>[type]{}
	\end{Syntax}
It sets the font size, series, face as defined by \Meta{type}, \Meta{type} being one of \Keylst{Oarg,Marg,Parg,Xarg,Macro,Code,Key,KeyVal,Option,Value,Default}. The star version uses bold.
\end{Macros}


\begin{Macros}{\MarginNote}
	\begin{Syntax}%
		\Macro{\MarginNote}{text}
	\end{Syntax}
As the name implies, to add small margin notes.
\end{Macros}


\begin{Macros}{\dcAuthor,\dcDate,\dcTitle,\dcMakeTitle}
	\begin{Syntax}%
		\Macro{\dcAuthor}{name}
		\Macro{\dcDate}{date}
		\Macro{\dcTitle}{title}
		\Macro{\dcMakeTitle}{}
	\end{Syntax}
Those allow one to define (as in standard article, book, report classes) the document \emph{author}, \emph{date} and \emph{date} \Macro{\dcMakeTitle}{} will write a typical title+author heading (as in the article class).
\end{Macros}

\begin{Envs}{dcAbstract}
	\begin{Syntax}%
		\Macro{\begin{dcAbstract}}{}  		\Macro{\end{dcAbstract}}{}
	\end{Syntax}
Same as above, for the abstract.
\end{Envs}




\end{document}