summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-12-20 00:30:59 +0000
committerKarl Berry <karl@freefriends.org>2012-12-20 00:30:59 +0000
commit71441df00e80ebb3470475a2317e5b324011624b (patch)
treea37fb136d233dec2919dd2119582762f3017059f /Master/texmf-dist/source
parent85a0b806cd76517912b1f46e45876f930920134e (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.dtx434
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} %
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%