refenums

git-svn-id: svn://tug.org/texlive/trunk@32430 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 400 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/refenums/LICENSE b/Master/texmf-dist/doc/latex/refenums/LICENSE
new file mode 100644
index 00000000000..2efdeab9555
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refenums/LICENSE
@@ -0,0 +1,15 @@
+Copyright 2013 Oliver Kopp, Tobias Binz
+
+This work may be distributed and/or modified under the conditions of
+the LaTeX Project Public License, version 1.3c of the license.
+The latest version of this license is in
+  http://www.latex-project.org/lppl.txt
+and version 1.3c or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status "maintained".
+
+The Current Maintainer and author of this work is Oliver Kopp.
+
+This work consists of the files refenums.sty, demo.tex, README, README.md, and test/demo-sec-param.tex.
+In case files are not listed here, but available at https://github.com/koppor/refenums, these additional files also form part of this work.
diff --git a/Master/texmf-dist/doc/latex/refenums/README.md b/Master/texmf-dist/doc/latex/refenums/README.md
new file mode 100644
index 00000000000..9ff61d70d5e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refenums/README.md
@@ -0,0 +1,91 @@
+# ReferenceableEnumElement
+
+This package provides commands to define enumerable items with a number and a long name, which can be referenced referenced later with the name or just the short form.
+For instance, "Milestone M1: Specification created" can be defined and later on be referenced with `M1` or `M1 ("Specification created")`.
+The text in the references is derived from the definition and also rendered as hyperlink to the definition.
+Thus, a change of the definition also leads to a change of all references to the text.
+This ensures consistency in the text.
+
+## Usage
+
+```
+\usepackage{refenums}
+```
+
+### Define the "Referenceable Enum Environment"
+
+Decide for `<EnumId>`.
+E.g., `req`.
+
+#### Initialize
+`\setupRefEnums{<EnumId>}{<PrintName>}`
+
+In case `<PrintName>` is set to `ONLYSHORT`, only the short name is used.
+
+Optional parameter: Separator between `<EnumId>` and number.
+
+#### (Optional) Define shorthand macro to define the macros for referencing
+
+`\newcommand{\def<EnumId>}[2]{\defRefEnum{<EnumId>}{#1}{#2}}`
+
+
+### Usage in the text
+
+#### Define a single enum
+* `\defRefEnum{<EnumId>}{<FullName>}{<LabelId>}` (always supported)
+* `\def<EnumId>{<FullName>}{<LabelId>}` (when the shorthand command is defined)
+
+#### Define a single enum using the inline format
+`\defineReferenceableEnumElementInline{<EnumId>}{<FullName>}{<LabelId>}`.
+Using this, a enumeration similar to the ones of the `inparaenum` environment is possible.
+`inparaenum` is offered by the [paralist package].
+
+#### Referencing
+ 
+* `\refEnumFull{<EnumId>}{<LabelId>}` = `<EnumId>-<Counter> ("<FullName>")`, e.g. `R-1 ("Quality")`
+* `\refEnumFullP{<EnumId>}{<LabelId>}` is the long form for `\refEnumFull'.
+* `\refEnumFullT{<EnumId>}{<LabelId>}` = `<EnumId>-<Counter>: "<FullName>"`, e.g. `R-1: "Quality"`
+* `\refEnum{<EnumId>}{<LabelId>}` = `<EnumId>-<Counter>`, e.g. `R-1`
+* References to the label
+  * `\nameref{enum:<EnumId>:<LabelId>}` = `<FullName>`
+  * `\ref{enum:<EnumId>:<LabelId>}` = `<Counter>`, e.g. `1`
+
+ 
+## Example
+
+**Initialize**: `\setupRefEnums{R}{Requirement}`
+
+**Define a single enum**: `\defRefEnum{R}{Quality}{qual}`.
+When you want to put the element in a section, use the optional parameter:
+`\defRefEnum[section]{R}{Quality}{qual}`
+
+**Referencing**:
+
+* Reference only Name + Number: `\refEnum{R}{qual}`
+* Full reference with the print name in brackets: `\refEnumFull{R}{qual}`
+* Full reference with the print name appended after ":": `\refEnumFullT{R}{qual}`
+
+**See also** [demo.tex](demo.tex).
+
+
+## Tuning
+
+When defining a referenceable element, this element is enclosed using `\refenumenclosing` for normal enums and `\refenumenclosinginline` for inline enums.
+These commands can be redefined after package usage.
+
+## TODO
+
+* The decision to put the enum in a section should be taken at `\setupRefEnums` not at `\defRefEnum`.
+* Enable automatically generating `\def<EnumId>` at `\setupRefEnums` via a package parameter.
+
+
+## Source code
+
+The latest source code is available at https://github.com/koppor/refenums
+
+## Files
+
+* [refenums.sty](refenums.sty): the package
+* [demo.tex](demo.tex): small demonstration
+
+  [paralist]: http://mirror.ctan.org/tex-archive/macros/latex/contrib/paralist/
diff --git a/Master/texmf-dist/doc/latex/refenums/demo.pdf b/Master/texmf-dist/doc/latex/refenums/demo.pdf
new file mode 100644
index 00000000000..9f44720f707
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refenums/demo.pdf
diff --git a/Master/texmf-dist/doc/latex/refenums/demo.tex b/Master/texmf-dist/doc/latex/refenums/demo.tex
new file mode 100644
index 00000000000..ca41e7382db
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refenums/demo.tex
@@ -0,0 +1,108 @@
+\documentclass[parskip=full]{scrartcl}
+
+\usepackage[colorlinks]{hyperref}
+\usepackage{refenums}
+
+%Always add a dot behind the definition
+\renewcommand{\refenumenclosing}[1]{#1.}
+
+
+\begin{document}
+
+\title{Demonstation of the refenums package}
+\date{}
+\author{}
+\maketitle
+
+\vspace{-12ex}
+This documents demonstrates the usage and results of the \href{http://mirror.ctan.org/tex-archive/macros/latex/contrib/refenums/}{refenums} package.
+All content appearing in this work is fictitious.
+Any resemblance to real artefacts, items, or persons, living or dead, is purely coincidental.
+
+\Crefrange{sec:reqs}{sec:milestones} show defined referenceable enums.
+\Cref{sec:discussion} references the defined enums.
+
+\tableofcontents
+\clearpage
+
+%Setup ``requirements''
+\setupRefEnums{R}{Requirement}
+
+%Setup ``capabilities'', without any separator
+\setupRefEnums[]{C}{Capability}
+
+%Setup ``Notes'' showing the usage of defineReferenceableEnumElementInline
+\setupRefEnums{N}{Note}
+
+%Setup ``Steps'' not having a print form
+\setupRefEnums[ ]{Step}{ONLYSHORT}
+
+%Setup ``Issue'' not having a print form
+\setupRefEnums[ ]{Issue}{ONLYSHORT}
+
+%Setup ``Milestones'' where the print name and the short name is combined
+\setupRefEnums[COMBINED]{M}{Milestone}
+
+
+\section{Requirements}
+\label{sec:reqs}
+\defRefEnum{R}{Scalability}{sca}
+We see scalability as important requirement.
+
+\defRefEnum{R}{Portability}{port}
+We also see portability as important requirement.
+
+
+\section{Capabilities}
+\defRefEnum{C}{Maintainability}{maint}
+
+\section{Notes}
+\defRefEnumInline{N}{Blue}{blue} It should be a blue note, shouldn't it?
+\defRefEnumInline{N}{Red}{Red} There should also be a red note, shouldn't it?
+
+
+\section{Steps}
+\label{sec:steps}
+
+\defRefEnum[subsection]{Step}{Requirements Analysis}{rqa}
+\label{sec:rqa}
+The heading is defined using the macro.
+
+\defRefEnum[subsection]{Step}{Software Specification}{spec}
+The heading is defined using the macro.
+
+
+\section{Issues}
+\defRefEnum{Issue}{Fictional}{fi}
+
+\defRefEnum{Issue}{Unrealistic}{unr}
+
+
+\section{Milestones}
+\label{sec:milestones}
+\defRefEnum[subsection]{M}{Basic Model}{bm}
+
+
+\section{Discussion}
+\label{sec:discussion}
+In \cref{sec:reqs}, we discussed \refEnumFull{R}{sca} and \refEnumFull{R}{port}.
+
+We showed the capability \refEnumFull{C}{maint}.
+
+We also had a note \refEnumFull{N}{blue}.
+
+In \cref{sec:steps}, we started with \refEnumFull{Step}{rqa}.
+\LaTeX{} put that step into \cref{sec:rqa}.
+Afterwards, \refEnumFull{Step}{spec} has been described.
+
+Some issues such as \refEnumFull{Issue}{fi} were raised.
+
+First, the milestone \refEnumFull{M}{bm} has to be reached.
+
+Following properties are the most important ones:
+\begin{itemize}
+\item \refEnumFullT{R}{sca}
+\item \ldots
+\end{itemize}
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/refenums/test/demo-sec-param.tex b/Master/texmf-dist/doc/latex/refenums/test/demo-sec-param.tex
new file mode 100644
index 00000000000..ebb3b3d1150
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/refenums/test/demo-sec-param.tex
@@ -0,0 +1,34 @@
+\documentclass{article}
+
+%required by referenceableenumelement
+\usepackage{csquotes}
+\usepackage{ifthen}
+\usepackage{etoolbox}
+\usepackage{hyperref}
+\usepackage[capitalise,nameinlink]{cleveref}
+
+%Always add a dot behind the definition
+\newcommand{\thighlight}[1]{#1.}
+
+\input{../referenceableenumelement}
+
+\begin{document}
+
+%Setup ``Steps'' not having a print form
+\setupRefEnums[ ]{Step}{ONLYSHORT}
+
+\section{Steps}
+\label{sec:steps}
+
+\defRefEnum[subsection]{Step}{Requirements Analysis}{rqa}
+\label{sec:rqa}
+The heading is defined using the macro.
+
+%to show that the links are working: start a new page
+
+\section{Discussion}
+
+In \cref{sec:steps}, we started with \refEnumFull{Step}{rqa}.
+\LaTeX{} put that step into \cref{sec:rqa}.
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/tex/latex/refenums/refenums.sty b/Master/texmf-dist/tex/latex/refenums/refenums.sty
new file mode 100644
index 00000000000..1839168cf51
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/refenums/refenums.sty
@@ -0,0 +1,152 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{refenums}
+  [2013/12/16 v1.1.0 Referenceable enumerated items (refenums.sty)]
+
+% This package provides commands to define enumerable items with a number
+% and a long name, which can be referenced referenced later with the name
+% or just the short form. For instance, "Milestone M1: Specification created"
+% can be defined and later on be referenced with `M1` or
+% `M1 ("Specification created")`. The text in the references is derived from
+% the definition and also rendered as hyperlink to the definition.
+% Thus, a change of the definition also leads to a change of all references
+% to the text. This ensures consistency in the text.
+
+% The latest source code is available at https://github.com/koppor/refenums
+
+\RequirePackage{csquotes}
+\RequirePackage{ifthen}
+\RequirePackage{hyperref}
+\RequirePackage[capitalise,nameinlink]{cleveref}
+
+%Defines command \refenumenclosing and \refenuminlineenclosing if it is not already defined
+\ifthenelse{\isundefined{\refenumenclosing}}{\newcommand{\refenumenclosing}[1]{#1}}{}
+\ifthenelse{\isundefined{\refenuminlineenclosing}}{\newcommand{\refenuminlineenclosing}[1]{\emph{#1}}}{}
+
+% tip by http://tex.stackexchange.com/a/73710/9075
+\makeatletter
+ \newcommand{\labelname}[1]{% \labelname{<stuff>}
+  \def\@currentlabelname{#1}}%
+\makeatother
+
+% Setup environment
+% Called ONCE for each enum
+%
+% #1: (optional) the seperator between EnumId and Number. Default: "-". If set to COMBINED, the output format changes to <PrintName> <EnumId><Number>
+% #2: Enum Id (no spaces, only characters), also used later in defineReferenceableEnumElement
+% #3: Print Name of enum type, if "ONLYSHORT" then only the short name is used and a long name never printed
+\newcommand{\setupRefEnums}[3][-]{%
+%Define global counter
+\newcounter{#2}
+
+%Store print name
+\expandafter\newcommand\csname #2PrintName\endcsname{#3}
+
+%Store separator
+%tipp by http://tex.stackexchange.com/a/64019/9075
+\expandafter\newcommand\csname #2Separator\endcsname{#1}
+
+%Store COMBINED and setup cref
+\newtoggle{#2Combined}
+\ifthenelse{%
+\equal{#1}{COMBINED}}{%
+\toggletrue{#2Combined}
+\crefformat{#2}{##2#2##1##3}
+\Crefformat{#2}{##2#2##1##3}
+}{%
+\togglefalse{#2Combined}
+\crefformat{#2}{##2#2#1##1##3}
+\Crefformat{#2}{##2#2#1##1##3}
+}
+
+%Store ONLYSHORTCONFIG
+\newtoggle{#2OnlyShort}
+\ifthenelse{%
+\equal{#3}{ONLYSHORT}}{%
+\toggletrue{#2OnlyShort}
+}{%
+\togglefalse{#2OnlyShort}
+}
+
+%End of definition of setupRefEnums
+}
+
+%internal command, used only at defineReferenceableEnumElement
+% #1: Enum Id (no spaces, only characters), also used to print short form of enum and to reference the setup at setupRefEnums
+% #2: Full Name of the enum to be defined
+\newcommand{\defRefEnumHelper}[2]{%
+% \arabic{#1} returns the counter value
+\iftoggle{#1OnlyShort}{%
+#1\csname #1Separator\endcsname\arabic{#1}: #2%
+}{%
+\iftoggle{#1Combined}{%
+\csname #1PrintName\endcsname\ #1\arabic{#1}: #2%
+}{%
+\csname #1PrintName\endcsname\ \arabic{#1} (#1\csname #1Separator\endcsname\arabic{#1}): #2%
+}%
+}%
+}%
+
+% Generic command to define counter elements
+% Called for EACH element
+%
+% #1: (optional) the command to wrap the text under. Defaults to refenumenclosing
+% #2: Enum Id (no spaces, only characters), also used to print short form of enum and to reference the setup at setupRefEnums
+% #3: Full Name of the enum to be defined
+% #4: Label Id of the enum when referencing it
+\newcommand{\defRefEnum}[4][refenumenclosing]{%
+%increase counter
+\refstepcounter{#2}%
+%
+%store the ``caption'' into a sepcial variable being used later for referencing
+\labelname{#3}%
+%
+%label directly put after refstepcounter to enable sectioning commands to be used as enumeration
+\label{enum:#2:#4}%
+%
+%Print out the thing
+\csname #1\endcsname{\defRefEnumHelper{#2}{#3}}%
+%
+}
+
+
+% Same as \defRefEnum but for inline referenceable elements!
+% One uses either without ``Inline'' or with ``Inline'' for a group of types
+\newcommand{\defRefEnumInline}[4][refenuminlineenclosing]{%
+ \refstepcounter{#2}%
+ \csname #1\endcsname{(#2\csname #2Separator\endcsname\arabic{#2}) #3}%
+ \labelname{#3}%
+ \label{enum:#2:#4}%
+}
+
+
+% Generic command to reference to an enum. The print name is put in brackets after the identifier.
+%
+% Output: <EnumId><Num> (``<PrintName>'')
+%
+% #1: Enum Id (no spaces, only characters!)
+% #2: Label Id
+\newcommand{\refEnumFullP}[2]{%
+ \refEnum{#1}{#2}
+ (\enquote{\nameref{enum:#1:#2}})%
+}
+
+
+% Generic command to reference to an enum. The print name is put in quotes after the identifier.
+%
+% Output: <EnumId><Num>: ``<PrintName>''
+%
+% #1: Enum Id (no spaces, only characters!)
+% #2: Label Id
+\newcommand{\refEnumFullT}[2]{%
+ \refEnum{#1}{#2}: \enquote{\nameref{enum:#1:#2}}%
+}
+
+
+% \refEnumFull defaults to \efEnumFullP
+\let\refEnumFull\refEnumFullP
+
+
+\newcommand{\refEnum}[2]{%
+  \cref{enum:#1:#2}%
+}
+\endinput