diff options
author | Karl Berry <karl@freefriends.org> | 2012-12-20 00:30:59 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-12-20 00:30:59 +0000 |
commit | 71441df00e80ebb3470475a2317e5b324011624b (patch) | |
tree | a37fb136d233dec2919dd2119582762f3017059f /Master/texmf-dist/source | |
parent | 85a0b806cd76517912b1f46e45876f930920134e (diff) |
conceps (19dec12)
git-svn-id: svn://tug.org/texlive/trunk@28579 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/latex/concepts/concepts.dtx | 434 |
1 files changed, 0 insertions, 434 deletions
diff --git a/Master/texmf-dist/source/latex/concepts/concepts.dtx b/Master/texmf-dist/source/latex/concepts/concepts.dtx deleted file mode 100644 index 2fd174bb89a..00000000000 --- a/Master/texmf-dist/source/latex/concepts/concepts.dtx +++ /dev/null @@ -1,434 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% % -% 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} % -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |