summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/concepts/concepts.tex
blob: 70c2c5c1f5117ea29dd56ce1b30af9099915c030 (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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                              %
%  Copyright (C) 2012 by Michiel Helvensteijn - www.mhelvens.net               %
%                                                                              %
%  http://latex-concepts.googlecode.com                                        %
%                                                                              %
%  This work may be distributed and/or modified under the                      %
%  conditions of the LaTeX Project Public License, either                      %
%  version 1.3 of this license or (at your option) any later                   %
%  version. The latest version of this license is in                           %
%      http://www.latex-project.org/lppl.txt                                   %
%  and version 1.3 or later is part of all distributions of                    %
%  LaTeX version 2005/12/01 or later.                                          %
%                                                                              %
%  This work has the LPPL maintenance status `author-maintained'.              %
%                                                                              %
%  The Current Maintainer of this work is Michiel Helvensteijn.                %
%                                                                              %
%  This work consists of the files concepts.tex and concepts.sty.              %
%                                                                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[a4paper]{packagedoc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Setup                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\moretexcs{%
  NewConcept,ConceptOption,ConceptName,ConceptSymbol,%
  ConceptSymbols,ConceptNameAndSymbols,delta,d,product,p,%
  prd%
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Global Changes                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\changes{0.0.1}{2012/11/16}{initial version}
\changes{0.0.2}{2012/11/25}{put the package into a .dtx file}
\changes{0.0.3}{2012/12/01}{separated the .dtx file from the .sty file}
\changes{0.0.4}{2012/12/08}{finished the documentation and made a few fixes}
\changes{0.0.5}{2012/12/18}{implemented symbol-list commands and improved documentation}
\changes{0.0.6}{2013/1/1}{made concept `options' mandatory + fixed some spacing bugs}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\maketitle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction and Motivation}                                          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Documents with a lot of formal notation (such as papers about mathematics or
theoretical computer science) can introduce a number of concepts that need
to be managed. They'll have \emph{names}, \emph{descriptions} and associated
\emph{symbols} that need to be typeset, as well as \emph{relations} between them.

I'm now writing my PhD thesis in the field of Theoretical Computer Science.
It will be especially heavy with definitions. I need to make sure that every
symbol is associated with no more than one concept and that all names and
symbols are consistently used. I'll also need to generate a glossary with
this information. But I don't want to manually keep track
of all that. It's error-prone and it takes time. I'd rather focus on the theory.

There are already techniques and packages that help lighten the load:
%
\begin{itemize}
  \item Rather than use any names or symbols directly in the text, declare
        a macro for each one. If you ever need to change one, you'll only
        have to do it in one place. You'll also be far less likely to
        introduce any typos.
  \item There are packages out there to keep track of and output a glossary%
        \footnote{It is sometimes called a nomenclature.
                  The distinction is subtle.}.
\end{itemize}

But I'm not aware of any technique or package to ensure I'm not
using a name or symbol inconsistently, thereby potentially
confusing the reader. And even if there was, using all these techniques at the
same time is still a lot of overhead.

I wrote the \textsf{concepts} package to automate all this stuff for me. Every
time I introduce a new concept in my thesis I `declare' it once. The package
then defines all necessary macros for me and checks that I'm using them
properly.

In \textsf{concepts}~\fileversion{}, most of the above already works but it
cannot generate a glossary yet. In future versions, it will interface with
the \textsf{glossaries} package to accomplish this, and more.

I'm also planning to implement a rudimentary typesystem, to catch even more
kinds of mistakes in symbol usage. Also, I may want to integrate the
|ligature| option from the \textsf{semantic} package, which allows you to
choose arbitrary characters to typeset your symbols in math mode (with some
restrictions).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Usage}                                                                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Every concept first has to be declared using the |\NewConcept| macro.
Afterwards, its name and associated symbols can by typeset using other macros.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\NewConcept}{
  \marg{concept key} \marg{options}
}

Every concept needs a unique \meta{concept key}, by which it will be identified
for the rest of the document. This key can also be used to automatically
derive the name of the concept as well as the macro used to typeset the name.

Then you'll want to add \meta{options}. This argument takes
a comma-separated list of |key=value| pairs. The following is a list of available
options. Note that the option names are case-sensitive:
%
\begin{description}
\item[name] the name of the concept\\
            --- default: \meta{concept key}
\item[Name] the capitalized name of the concept, for use in the beginning of
            a sentence\\
            --- default: \meta{name} with the first letter capitalized
\item[plural] the plural form of the name\\
              --- default: \meta{name}|s|
\item[Plural] the capitalized, pluralized name of the concept\\
              --- default: \meta{plural} with the first letter capitalized
\item[namecmd] the `short' command that may be used to typeset the name of
               this concept; this option *has* to be specified for
               any command to be defined, but the |=value| part may
               be omitted to get the default\\
               --- default: |\|\meta{concept key}
\item[symbols] a comma-separated list of symbols that may represent instances
               of this concept, delimited by curly brackets\\
               --- default: |{}| (the empty list)
\item[symbolcmd] the `short' command that may be used to typeset a
                 specific symbol
\end{description}

Here are a few examples which will also be used to illustrate the other commands:

\begin{latex-example}
\NewConcept{swproduct}{
  name      = software product,  % options 'plural', 'Plural'
  Name      = Software Product,  %   are implicitly defined
  namecmd   = \product,          % defines \product
  symbols   = {p},               % p represents a product
  symbolcmd = \p                 % defines \p
}
\end{latex-example}
%
\begin{latex-example}
\let\delta\relax \let\d\relax  % I won't be using these
\NewConcept{delta}{
  namecmd,                     % defines \delta
  symbols   = {x, y, z},       % x, y and z represent deltas
  symbolcmd = \d               % defines \d
}
\end{latex-example}

There are certain restrictions on new concept declarations. You may
not use the same \meta{concept key} more than once. You may not use the same
symbol for more than one concept (this is a feature; the package will
report an error if you do). Also, both \meta{namecmd} and \meta{symbolcmd} are
subject to the rules governing |\newcommand|. They may not be reused, or you
will see a standard \LaTeX{} error. Finally, any value you supply must behave
properly in an expansion-only context, e.g. be robust.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\ConceptOption}{
  \marg{concept key} \marg{option key}
}

This command can be used to get back any option value given a
specific \meta{concept~key} and \meta{option key}. For example:

\begin{latex-example-show}
\ConceptOption{delta}{Plural}
\end{latex-example-show}
%
\begin{latex-example-show}
\edef\prd{\ConceptOption{swproduct}{namecmd}}%
{\ttfamily\expandafter\detokenize\expandafter{\prd}}%
  expands to ``\prd''.
\end{latex-example-show}

|\ConceptOption| is `fully expandable', meaning that it can expand at
least down to the value that was given to the option. (This is not (yet)
guaranteed for the other commands.)

As you can observe from the |\product| example above, options that expect a
command sequence are stored with an accompanying |\noexpand|. That means that
in an |\edef| context, |\ConceptOption| expands down to the stored command but
no further. After that you can expand it further if you wish.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\ConceptName}{
  \movarg{\textasciicircum} \movarg{*} \marg{concept key}
}

With this command you can typeset the name of the concept with \meta{concept key}
in any of four forms. The |^| modifier gives you the capitalized version. The |*|
modifier gives you the plural version. The combination gives you both. The order
between |^| and |*| doesn't matter.

\begin{latex-example-show}
\ConceptName^*{delta} can transform a \ConceptName{swproduct}.
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemetamacro{namecmd}{
  \movarg{\textasciicircum} \movarg{*}
}

This is the `short' version of |\ConceptName|, specific for each concept that
was declared with the |namecmd| option. It supports the same modifiers.

\begin{latex-example-show}
\delta^* can easily transform a \product.
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\ConceptSymbol}{
  \marg{concept key} \oarg{symbol index}
}

This command typesets a specific symbol associated with a a given concept. It is
always typeset in math mode. Specify the concept with the \meta{concept key}
and the symbol with the \meta{symbol index}.

The index is 1-based and points to a place in the symbol list provided with the
concept options. If a concept has only one allocated symbol the index may be
omitted. If there is more than one symbol, the index is mandatory.

\begin{latex-example-show}
\product^* have symbols like \ConceptSymbol{swproduct}.
\end{latex-example-show}
%
\begin{latex-example-show}
$\ConceptSymbol{delta}[2] \cdot \ConceptSymbol{delta}[1] =
 \ConceptSymbol{delta}[1] \cdot \ConceptSymbol{delta}[2]$
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemetamacro{symbolcmd}{
  \momarg{symbol index}
}

This is the `short' version of |\ConceptSymbol|, specific for each concept that
was declared with the |symbolcmd| option. The optional index is given directly
following the command itself. It doesn't need any delimiters. However, you are
allowed to use square brackets. See the list-variation of this short command
below.

\begin{latex-example-show}
$(\d2 \cdot \d1)(\p) = \d2(\d1(\p)) = \d2(\p') = \p''$
\end{latex-example-show}

As you can see, this short construct requires a lot less space than the
full |\ConceptSymbol| command, so its use is recommended for readability.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\ConceptSymbols}{
  \marg{concept key}    \oarg{separator}
  \oarg{last separator} \marg{symbol indices}
}

This command typesets a \meta{separator} separated list of symbols associated
with the given concept, optionally with a different \meta{last separator}. Specify
the concept with the \meta{concept key} and the symbol-list with the
\meta{symbol indices}. \meta{separator} defaults to |,| and \meta{last separator}
defaults to \meta{separator}. The whole list is typeset in math mode, so if
you'd like a non-math delimiter, you need to use \verb|$| tokens.

The indices are 1-based and point to a place in the symbol list provided with the
concept options. The index-list is mandatory, but can be empty.

\begin{latex-example-show}
The symbols \ConceptSymbols{delta}{1,2,3} represent \delta*.
\end{latex-example-show}
%
\begin{latex-example-show}
$\{\ConceptSymbols{delta}[;]{1,1,1}\}$ contains only \d1.
\end{latex-example-show}
%
\begin{latex-example-show}
What about \ConceptSymbols{delta}[,][$ and $]{3, 2, 1}?
\end{latex-example-show}
%
\begin{latex-example-show}
xx\ConceptSymbols{delta}{}xx
\end{latex-example-show}

If you need any symbol in the resulting list to have some decoration (like a
prime, subscript or superscript) you can decorate the corresponding index
accordingly. This currently only works for decorations that would be specified
\emph{after} the symbol. Each element of \meta{symbol indices} still needs to
start with the index itself:

\begin{latex-example-show}
\ldots such as the symbols in
  $(\ConceptSymbols{delta}{1_1, 2'', 3^{\d1(\p)}})$.
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemetamacro{symbolcmd}{
  \oarg{symbol indices}
}

This is the `short' version of |\ConceptSymbols|, specific for each concept that
was declared with the |symbolcmd| option. The \meta{symbol indices} list needs
to be delimited by square brackets as shown below.

\begin{latex-example-show}
$\forall \d[1,2] \in D:\ \d1 \| \d2\ \Rightarrow\ {}
  \exists \d[3'] \in D:\ \d1 \prec \d3' \land \d2 \prec \d3'$
\end{latex-example-show}
%
\begin{latex-example-show}
xx\d[]xx\p[]xx
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemacro{\ConceptNameAndSymbols}{
  \movarg{\textasciicircum} \marg{concept key}
  \oarg{separator} \oarg{last separator}
  \marg{symbol indices}
}

This command is the `hybrid' version of |\ConceptName| and |\ConceptSymbols|.
It typesets the name of the concept followed by a \meta{separator} separated list
of symbols associated with the given concept, optionally with a different
\meta{last separator}. Specify the concept with the \meta{concept key} and the
symbol-list with \meta{symbol~indices}. \meta{separator} defaults to |,| and
\meta{last separator} defaults to |$ and $|. The name is typeset in text mode and
the list is typeset in math mode.

The indices are 1-based and point to a place in the symbol list provided with the
concept options. The index-list is mandatory and cannot be empty.

You can still supply the |^| modifier to capitalize the name but the choice
between singular and plural form is determined by the number of \meta{symbol indices}.

\begin{latex-example-show}
We use \ConceptNameAndSymbols{delta}[,][$ and also $]{1,2,3}.
\end{latex-example-show}

For some other neat tricks, read the documentation of |\ConceptSymbols| above.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\describemetamacro{namecmd}{
  \movarg{\textasciicircum} \oarg{symbol indices}
}

This is a `short' version of |\ConceptNameAndSymbols|,
specific for each concept that was declared with the |namecmd| option.
The \meta{symbol indices} list needs to be delimited by square brackets
as shown below. The list is comma-delimited and the last (or only) delimiter is
the word `and'.

\begin{latex-example-show}
\delta^[1,2] come before \delta[3]. 
\end{latex-example-show}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Future Work}                                                          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Everything up to this version of the package has been a bit of an experiment
for me. A way to get me started. I may still fix one or two issues for the
0.0.x series, but I will soon start from scratch with all I've learned.

There will be two major changes starting from version 0.1.0. First of all, the
package will be built on top of the |glossaries| package, which already does
much of the work I'm now doing manually. This was always the plan, as we'll
want to typeset a glossary with our concepts, and I don't want to reinvent
the wheel. The |glossaries| package is actively developed and has a great
amount of features we can take advantage of. Secondly, I will program the
0.1.0 series using \LaTeX3.

Here is an incomplete list of the features I am planning to implement:
\begin{itemize}
  \item full integration with the \textsf{glossaries} package
  \item typesetting a \emph{summary} of the concepts introduced in each chapter / section
  \item management of \emph{tuples} and \emph{sets} of concept instances
  \item management of \emph{subconcepts} plus a rudimentary \emph{typesystem} that
        ensures concept instances are not used where a different concept is expected
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%