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