refenums – ReferenceableEnumElements

Define numbered items with a title, such as requirements, risks, or milestones, and reference them by identifier (e.g., Req-1), title, or both, with hyperlinks to the definition

The package provides commands to define numbered items with a title, such as requirements, risks, or milestones, and to reference them by identifier, title, or both, with hyperlinks to the definition. For instance, "Milestone M1: Specification created" can be defined and later on be referenced with M1, Milestone M1, or M1 ("Specification created"). The references are derived from the definition, so they stay consistent when it changes. The package builds on zref-clever, which allows for referencing several items at once, e.g., "Risks R1 and R2".

Usage

\usepackage{refenums}

% Once per kind of item: identifier and name
\setupRefEnum{Req}{Requirement}

% Define an item: title and label
\defReq{Detect concurrent modification}{detect}
If the library file changed since the save started, the save is aborted.

% Reference it
\refReq{detect}                % Req-1
\refReq*{detect}               % Requirement Req-1
\refReqFull{detect}            % Req-1 ("Detect concurrent modification")
\refReqFull*{detect}           % Requirement Req-1 ("Detect concurrent modification")
\refReqFullColon{detect}       % Req-1: "Detect concurrent modification"
\refReqFullColon*{detect}      % Requirement Req-1: "Detect concurrent modification"
\refReqTitle{detect}           % Detect concurrent modification

\setupRefEnum{Req} creates the commands \defReq and \refReq… used above.

The definition prints "Requirement 1 (Req-1): Detect concurrent modification". All references are hyperlinks to it.

See refenums-demo.tex and its rendering refenums-demo.pdf, which shows the LaTeX code next to each result.

refenums needs LaTeX 2023-06-01 and zref-clever 0.4.0 or later. refenums loads hyperref and zref-clever itself; if you load them yourself, e.g., to pass options, load refenums after them.

Advanced usage

Long forms of the commands

\setupRefEnum{<EnumId>} creates these shorthands; the long forms take <EnumId> as first argument:

The \ref… commands except …Title have a starred form, which prefixes the print name, e.g., Requirement Req-1.

If a command with one of these names exists already, LaTeX reports an error; choose another <EnumId> then, or turn the shorthands off with \usepackage[shorthands=false]{refenums} and use the long forms.

\defRefEnumInline prints (<EnumId>-<Counter>) <FullName> within the text, similar to the inparaenum environment of paralist.

Referencing with zref-clever

• \refEnum*{<EnumId>}{<LabelId>} is short for \zcref{enum:<EnumId>:<LabelId>} of zref-clever, \refEnum for \zcref[noname].
• \zcref references several items at once, e.g., \zcref{enum:Req:detect,enum:Req:keep} prints Requirements Req-1 and Req-2.
• \refEnumTitle{<EnumId>}{<LabelId>} is short for \nameref{enum:<EnumId>:<LabelId>}; \ref{enum:<EnumId>:<LabelId>} prints the identifier.
• \refEnumFullP and \refEnumFullT are older names of \refEnumFull and \refEnumFullColon.

Options of \setupRefEnum

\setupRefEnum[<options>]{<EnumId>}{<PrintName>}

If <PrintName> is ONLYSHORT, only the short form is printed, e.g., Feature 1 with separator={ }.

Options (key-value, all optional), from the definition of an element to its references:

• inline: \def<EnumId> and \defRefEnum define each element inline, as \def<EnumId>Inline does, e.g., (Opt-1) Overwrite in place.
• enclosing=<name>: name of the command the heading of each element is wrapped in, e.g., subsection. Default: refenumenclosing (see Tuning).
• titleformat=<name>: name of the command the title of each element is wrapped in, e.g., textbf. Default: emph (italics), or none if enclosing names another command. Use titleformat={} for none. References to the title are not affected.
• combined: print <PrintName> <EnumId><Number>, e.g., Milestone M1.
• separator=<text>: separator between <EnumId> and number. Default: -. Use separator={} for none and separator={ } for a space.
• plural=<text>: plural of <PrintName>, printed by \zcref for several items. Default: <PrintName>s.

The older \setupRefEnums[<separator>][<enclosing>]{<EnumId>}{<PrintName>} takes the same settings as positional optional arguments, with COMBINED as separator for combined.

Tuning

The heading of an element is wrapped in \refenumenclosing (unless enclosing says otherwise), the one of an inline element in \refenuminlineenclosing. By default, \refenumenclosing prints the heading as is and \refenuminlineenclosing in italics. Both can be redefined after loading the package, e.g., \renewcommand{\refenumenclosing}[1]{#1.} adds a dot after each heading.

cleveref

refenums references with zref-clever; cleveref is supported for existing documents only. \cref prints the same identifiers as \refEnum, no matter whether cleveref is loaded before or after refenums. Only \setupRefEnum must come after \usepackage{cleveref}; otherwise, \cref prints ?? 1 for that enum.

Source code

The latest source code is available at https://github.com/koppor/refenums.

Files

• refenums.sty: the package
• refenums-demo.tex: small demonstration

Related packages

• See https://ctan.org/topic/label-ref for an overview.
• zref-clever (like cleveref) prints the type and number of a reference. refenums builds on zref-clever: \defRefEnum also prints the heading of an item, stores its title, and the references can include that title (\refEnumFull, \refEnumFullColon).
• In the context of chemistry, chemsec offers tailored functionality.

License

Copyright 2013 Oliver Kopp, Tobias Binz
Copyright 2014–2026 Oliver Kopp

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, refenums-demo.tex, and README.md. In case files are not listed here, but available at https://github.com/koppor/refenums, these additional files also form part of this work.