summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/concepts/concepts.dtx
blob: 2fd174bb89adcc00bb91858d9c3255aef297b004 (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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                              %
%  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.dtx and concepts.sty.              %
%                                                                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% 'ltxdoc' to typeset the documentation
%
\documentclass[a4paper]{ltxdoc}

%%% including the 'concepts' package itself
%
\usepackage{concepts}[2012/11/25]

%%% including other packages we need
%
\usepackage{etextools}
\usepackage{etoolbox}
\usepackage{framed}
\usepackage{color}
\usepackage{marginnote}
\usepackage{listings}      %1 syntax highlighting
\usepackage{lstautogobble} %2 ignore common indentation

%%% skip any indentation directly after a code block or macro signature
%
\makeatletter
	\newcommand*{\@noindentnext}{\everypar{{\setbox\z@\lastbox}\everypar{}}}
	\AfterEndEnvironment{codeframe}{\@noindentnext}
	\AfterEndEnvironment{uninterestingcodeframe}{\@noindentnext}
	\apptocmd{\marg}{\@noindentnext}{}{}
	\apptocmd{\oarg}{\@noindentnext}{}{}
	\apptocmd{\parg}{\@noindentnext}{}{}
	\pretocmd{\DescribeMacro}{\noindent\\}{}{}
\makeatother

%%% documentation options
%
\EnableCrossrefs         
\CodelineIndex
\RecordChanges

%%% title and author information
%
\GetFileInfo{concepts.sty}
\title{The \textsf{concepts} package\thanks{%
	This document corresponds to \textsf{concepts}~\fileversion, dated \filedate.%
	Development of this package is organized at \texttt{http://latex-concepts.googlecode.com}.%
	I am happy to receive feedback there.%
}}
\author{Michiel Helvensteijn \\ \texttt{mhelvens+latex@gmail.com}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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 keeping 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, this is all still a lot of
overhead.

I wrote the |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.

I'm also planning to implement a rudimentary typesystem, to catch even more
kinds of mistakes in symbol usage. There will also be additional ways of
typesetting concept-related stuff, such as useful sentence fragments.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Usage Prep                                                                   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%% formatting the code blocks
%
\setlength{\FrameSep}{0pt}
\setlength{\MacroIndent}{16pt}
\setlength{\MacrocodeTopsep}{2pt}

%%% switching between relevant and uninteresting code block coloring
%
\makeatletter
	\definecolor{uninterestingcodecolor}{rgb}{.4,.4,.4}
	\let\old@macro@font\macro@font

	\newenvironment{codeframe}{%
		\definecolor{shadecolor}{rgb}{.9,.9,.9}%
		\begin{shaded}%
	}{%
		\end{shaded}%
	}

	\newenvironment{uninterestingcodeframe}{%
		\vspace{-5mm}%
		\definecolor{shadecolor}{rgb}{.97,.97,.97}%
		\begin{shaded}%
		\def\macro@font{\color{uninterestingcodecolor}\old@macro@font}%
	}{%
		\end{shaded}%
	}
\makeatother

%%% meta-optional arguments (that means: without explicit [])
%
\makeatletter
	\newcommand*{\movarg}[1]{[ \verb|#1| ]\@noindentnext}
	\newcommand*{\momarg}[1]{[ \meta{#1} ]\@noindentnext}
\makeatother

%%% code blocks for examples
%
\lstdefinelanguage{latex}{
	language=[LaTeX]tex,
	moretexcs={detokenize,
	           NewConcept,ConceptOption,ConceptName,ConceptSymbol,
	           delta,product,p,d,prd},
	texcsstyle=*\bfseries
}

\lstnewenvironment{latexcode}{%
	\renewcommand{\ttdefault}{pcr}%
	\lstset{language=latex,basicstyle=\ttfamily\small,autogobble=true}%
}{}

\BeforeBeginEnvironment{latexcode}{\noindent\begin{codeframe}\noindent\begin{minipage}{\textwidth}\vspace{-2mm}}
\AfterEndEnvironment{latexcode}{\vspace{-2mm}\end{minipage}\end{codeframe}}

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

In short: 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} \oarg{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.

Usually, you'll also want to add \meta{options}. This optional 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 of this concept, given a numeric index
\end{description}

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

\begin{latexcode}
	\NewConcept{swproduct}[
	    name      = software product,  % options 'plural', 'Plural'
	    Name      = Software Product,  %   are implicitly defined
	    namecmd   = \product,          % defines \product
	    symbols   = {p, q, r},         % p, q, r represent products
	    symbolcmd = \p                 % defines \p
	]
\end{latexcode}\vspace{-4mm}

	\NewConcept{swproduct}[
	    name      = software product,  % options 'plural', 'Plural'
	    Name      = Software Product,  %   are implicitly defined
	    namecmd   = \product,          % defines \product
	    symbols   = {p, q, r},         % p, q, r represent products
	    symbolcmd = \p                 % defines \p
	]

\begin{latexcode}
	\let\delta\relax            % I won't be using the greek letter
	\let\d\relax                % or the 'dot under a letter' macro
	
	\NewConcept{delta}[
	    namecmd,                % defines \delta
	    symbols   = {x, y, z},  % x, y and z represent deltas
	    symbolcmd = \d          % defines \d
	]
\end{latexcode}

	\let\delta\relax            % I won't be using the greek letter
	\let\d\relax                % or the 'dot under a letter' macro
	
	\NewConcept{delta}[
	    namecmd,                % defines \delta
	    symbols   = {x, y, z},  % x, y and z represent deltas
	    symbolcmd = \d          % defines \d
	]

\noindent 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{latexcode}
	\ConceptOption{delta}{Plural}
\end{latexcode}

\noindent\fbox{\ConceptOption{delta}{Plural}}

\begin{latexcode}
	\edef\prd{\ConceptOption{swproduct}{namecmd}}
	{\ttfamily\expandafter\detokenize\expandafter{\prd}}%
	    expands to ``\prd''
\end{latexcode}

\noindent\fbox{%
	\edef\prd{\ConceptOption{swproduct}{namecmd}}%
	{\ttfamily\expandafter\detokenize\expandafter{\prd}}%
	    expands to ``\prd''%
}\\

\noindent |\ConceptOption| is `fully expandable', meaning that it can expand at
least down to the value that was given to the option. This is not guaranteed for
the |\ConceptName| and |\ConceptSymbol| commands, for instance.

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{latexcode}
	\ConceptName^*{delta} can transform a \ConceptName{swproduct}.
\end{latexcode}

\noindent\fbox{\ConceptName^*{delta} can transform a \ConceptName{swproduct}.}

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

\noindent\\\marginnote{\meta{namecmd}}
	\movarg{\textasciicircum} \movarg{*}\\

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

\begin{latexcode}
	\delta^* can easily transform a \product.
\end{latexcode}

\noindent\fbox{\delta^* can easily transform a \product.}

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

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

This command typesets a specific symbol associated with a a given concept. Specify
the concept by providing the \meta{concept key} and the symbol by giving 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{latexcode}
	$\ConceptSymbol{delta}[2] \cdot \ConceptSymbol{delta}[1] =
	 \ConceptSymbol{delta}[1] \cdot \ConceptSymbol{delta}[2]$
\end{latexcode}

\noindent\fbox{%
	$\ConceptSymbol{delta}[2] \cdot \ConceptSymbol{delta}[1] =
	 \ConceptSymbol{delta}[1] \cdot \ConceptSymbol{delta}[2]$%
}

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

\noindent\\\marginnote{\meta{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 (optionally with whitespace inbetween). To be
clear: the index doesn't need any delimiters.

\begin{latexcode}
	$(\d2 \cdot \d1)(\p1) = \d2(\d1(\p1)) = \d2(\p1') = \p1''$
\end{latexcode}

\noindent\fbox{$(\d2 \cdot \d1)(\p1) = \d2(\d1(\p1)) = \d2(\p1') = \p1''$}\\

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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 \LaTeX$_3$.

Here is an incomplete list of the features I am planning to implement:
\begin{itemize}
  \item full integration with the \textsf{glossaries} package
  \item commands to \emph{modify} existing concepts
  \item typesetting a \emph{summary} of the concepts introduced in each chapter / section
  \item typesetting \emph{sentence fragments} such as \fbox{\vphantom{W}$\d1, \d2, \d3$}
        using only the code |\d[1,2,3]|
        or \fbox{deltas $\d1, \d2, \d3$} using only |\delta[1,2,3]|
  \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}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Implementation Prep                                                          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\StopEventually{
	\PrintChanges
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Implementation}                                                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

We now show and explain the entire implementation in |concepts.sty|.

\DocInput{concepts.sty}

\Finale

\PrintIndex

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