From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/refenums/LICENSE | 15 ++ macros/latex/contrib/refenums/README | 1 + macros/latex/contrib/refenums/README.md | 99 ++++++++++++++ macros/latex/contrib/refenums/README.pdf | Bin 0 -> 126408 bytes macros/latex/contrib/refenums/demo.pdf | Bin 0 -> 82461 bytes macros/latex/contrib/refenums/demo.tex | 121 ++++++++++++++++ macros/latex/contrib/refenums/refenums.sty | 152 +++++++++++++++++++++ .../latex/contrib/refenums/test/demo-sec-param.tex | 34 +++++ 8 files changed, 422 insertions(+) create mode 100644 macros/latex/contrib/refenums/LICENSE create mode 120000 macros/latex/contrib/refenums/README create mode 100644 macros/latex/contrib/refenums/README.md create mode 100644 macros/latex/contrib/refenums/README.pdf create mode 100644 macros/latex/contrib/refenums/demo.pdf create mode 100644 macros/latex/contrib/refenums/demo.tex create mode 100644 macros/latex/contrib/refenums/refenums.sty create mode 100644 macros/latex/contrib/refenums/test/demo-sec-param.tex (limited to 'macros/latex/contrib/refenums') diff --git a/macros/latex/contrib/refenums/LICENSE b/macros/latex/contrib/refenums/LICENSE new file mode 100644 index 0000000000..2efdeab955 --- /dev/null +++ b/macros/latex/contrib/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/macros/latex/contrib/refenums/README b/macros/latex/contrib/refenums/README new file mode 120000 index 0000000000..42061c01a1 --- /dev/null +++ b/macros/latex/contrib/refenums/README @@ -0,0 +1 @@ +README.md \ No newline at end of file diff --git a/macros/latex/contrib/refenums/README.md b/macros/latex/contrib/refenums/README.md new file mode 100644 index 0000000000..d4d489d825 --- /dev/null +++ b/macros/latex/contrib/refenums/README.md @@ -0,0 +1,99 @@ +# refenums - ReferenceableEnumElements + +Define named items and provide back-references with that name + +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} +``` + +Load the package after all packages (hyperref, cleveref, ...). +For best results, use the `nameinlink` option at cleveref. +The option `capitalise` is also useful if you use cleveref's `\cref` command, therefore we recommend loading `cleveref` before `refenums` with follwing line: +`\usepackage[capitalise,nameinlink]{cleveref}` + + +### Define the "Referenceable Enum Environment" + +Decide for ``. +E.g., `req`. + +#### Initialize +`\setupRefEnums{}{}` + +In case `` is set to `ONLYSHORT`, only the short name is used. + +Optional parameter: Separator between `` and number. + +#### (Optional) Define shorthand macro to define the macros for referencing + +`\newcommand{\def}[2]{\defRefEnum{}{#1}{#2}}` + + +### Usage in the text + +#### Define a single enum +* `\defRefEnum{}{}{}` (always supported) +* `\def{}{}` (when the shorthand command is defined) + +#### Define a single enum using the inline format +`\defineReferenceableEnumElementInline{}{}{}`. +Using this, a enumeration similar to the ones of the `inparaenum` environment is possible. +`inparaenum` is offered by the [paralist package]. + +#### Referencing + +* `\refEnumFull{}{}` = `- ("")`, e.g. `R-1 ("Quality")` +* `\refEnumFullP{}{}` is the long form for `\refEnumFull'. +* `\refEnumFullT{}{}` = `-: ""`, e.g. `R-1: "Quality"` +* `\refEnum{}{}` = `-`, e.g. `R-1` +* References to the label + * `\nameref{enum::}` = `` + * `\ref{enum::}` = ``, 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` 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]: www.ctan.org/pkg/paralist diff --git a/macros/latex/contrib/refenums/README.pdf b/macros/latex/contrib/refenums/README.pdf new file mode 100644 index 0000000000..64db1041d8 Binary files /dev/null and b/macros/latex/contrib/refenums/README.pdf differ diff --git a/macros/latex/contrib/refenums/demo.pdf b/macros/latex/contrib/refenums/demo.pdf new file mode 100644 index 0000000000..c0b74b85d1 Binary files /dev/null and b/macros/latex/contrib/refenums/demo.pdf differ diff --git a/macros/latex/contrib/refenums/demo.tex b/macros/latex/contrib/refenums/demo.tex new file mode 100644 index 0000000000..f74589970b --- /dev/null +++ b/macros/latex/contrib/refenums/demo.tex @@ -0,0 +1,121 @@ +\documentclass[parskip=full]{scrartcl} + +\usepackage[colorlinks]{hyperref} +\usepackage[capitalise,nameinlink]{cleveref} +\usepackage{refenums} + +%Always add a dot behind the definition +\renewcommand{\refenumenclosing}[1]{#1.} + + +\begin{document} + +\title{Demonstration of the refenums package} +\date{} +\author{} +\maketitle + +\vspace{-12ex} +This documents demonstrates the usage and results of the \href{http://www.ctan.org/pkg/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{Other Steps} +\label{sec:osteps} + +This section shows how an enum can be reused. +One has to take care to use different labels as in the first usage. + +\setcounter{Step}{0} +\defRefEnumInline{Step}{Think}{think} First think. +\defRefEnumInline{Step}{Work}{work} Then work. + +\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. + +We reused the enumeration environment for other steps in \cref{sec:osteps}. +There, we started with \refEnumFull{Step}{think}. + +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/macros/latex/contrib/refenums/refenums.sty b/macros/latex/contrib/refenums/refenums.sty new file mode 100644 index 0000000000..e32343f3da --- /dev/null +++ b/macros/latex/contrib/refenums/refenums.sty @@ -0,0 +1,152 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{refenums} + [2014/01/03 v1.1.1 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{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{} + \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 +% #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: (``'') +% +% #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: : ``'' +% +% #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 diff --git a/macros/latex/contrib/refenums/test/demo-sec-param.tex b/macros/latex/contrib/refenums/test/demo-sec-param.tex new file mode 100644 index 0000000000..ebb3b3d115 --- /dev/null +++ b/macros/latex/contrib/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 -- cgit v1.2.3