@ -30,7 +30,9 @@ the labels they refer to appear in their document.
It is written in Plain TeX as much as possible
in order to make it compatible with a wide array of formats.
For the moment, it works out of the box with ConTeXt and LaTeX.
Its only dependency is [`simple kv` ](https://ctan.org/pkg/simplekv ).
Its only (optional) dependency is [`exp kv` ](https://ctan.org/pkg/expkv-bundle ),
but it may require other packages to work properly in some formats
(e.g. `zref` ](https://ctan.org/pkg/zref ) in LaTeX).
The file `main-test.pdf` provides a showcase of the abilities of _crossrefenum_ .
@ -86,14 +88,69 @@ The same invocations with the group-based syntax:
## Customization
Customizing is done by redefining configuration macros.
We describ e the general mechanism first .
Macros for double types are introduced at the end of this section .
There are two configuration interfaces:
one based on key-value lists, th e o ther on (re)defining macros .
These two interfaces can be used concurrently .
If you are not interested in using the key-value interface
or prefer not to depend on the `expkv` package,
you can deactivate it by defining `\crfnmNoKV` to anything other than `\relax`
before loading `crossrefenum` .
After having explained the general principles,
we
before we
For each configuration option, I
first how to use the key-value interface using `\crfnmsetup` ,
and second how to do the same thing with the low-level macros.
### General principles {#specialize-config-macros}
In this manual, “default” means “not type-specific”.
In this respect, “default” settings may be set be the user.
The key-value interface has the following syntax:
> \\crfnmsetup\[_“default” or type_\]{ _key1_ = _value1_, _key2_ = _value2_, … }
_type_ is a single or a double type (e.g. `page` or `pagenote` ).
The spaces around the equal signs and the commas are optional and ignored;
if a value contains leading or trailing spaces, it must be put inside a group
(e.g. `delimiter = {, }` ).
Under the hood, `\crfnmsetup` (re)defines the low-level configuration macros,
which you can also manipulate directly.
When successive calls to `\crfnmsetup` contradict one another, the last one prevails,
except that type-specific settings always have precedence over the default ones.
In the following subsections, I
corresponding to the default settings, which have `Default` in their name.
If you want to redefine a macro for a specific type,
simply replace `Default` with the (capitalized) name of the type
(e.g. `\crfnmPageEnumDelim` instead of `\crfnmDefaultEnumDelim` ).
Setting a value in the key-value interface or a macro to `\relax`
will cause `\crossrefenum` to fall back to the default value.
To set a configuration option to an absence of operation,
use an empty group (e.g. `\def\crfnmPageEnumDelim{}`
if you really don't want any delimiter between page numbers
while the default delimiter is a comma followed by a space).
Unless specified otherwise, the examples in the following subsections
correspond to the built-in configuration.
### Prefixes, delimiters and separators
Every simple type has two macros corresponding to the singular and plural prefixes
printed before the value of the reference. By default, they are set to :
You can define the singular and plural prefixes
printed before the value of the reference like this :
```{.tex}
\crfnmsetup[page]{sg={p.~}, pl={pp.~}}
\crfnmsetup[note]{sg={n.~}, pl={nn.~}}
\crfnmsetup[edpage]{sg={p.~}, pl={pp.~}}
\crfnmsetup[edline]{sg={l.~}, pl={ll.~}}
` ``
` \noindentation`{=context} which almost amounts to the built-in configuration:
` ``{.tex}
\def\crfnmPage{p.~}
@ -106,14 +163,31 @@ printed before the value of the reference. By default, they are set to:
\def\crfnmEdlines{ll.~}
` ``
Between successive items in an enumeration, ` \crossrefenum` calls ` \crfnmDefaultEnumDelim` or ` \crfnmDefaultBeforeLastInEnum`. By default, they are set to:
` \noindentation`{=context} (it would have been more accurate to write
` \crfnmsetup[edpage]{sg=\crfnmPage, pl=\crfnmPages}`).
The delimiters printed respectively between the successive references in an enumeration
and before the last one are set so:
` ``{.tex}
\crfnmsetup[default]{
delimiter = {, },
before last reference = { and }
}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultEnumDelim{, }
\def\crfnmDefaultBeforeLastInEnum{ and }
` ``
The beginning and the end of a range are separated by ` \crfnmDefaultRangeSep`. By default :
The separator in a range is set like this :
` ``{.tex}
\crfnmsetup[default]{range separator = –
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultRangeSep{–
@ -121,24 +195,37 @@ The beginning and the end of a range are separated by `\crfnmDefaultRangeSep`. B
### Collapsable and non-collapsable types {#collapsable-types}
The macro ` \crfnmDefaultC ollapsable` defines if ranges are allowed.
T he default configuration is:
The configuration option ` c ollapsable? ` and
t he macro ` \crfnmDefaultCollapsable` define if ranges are allowed.
The built-in configuration corresponds to:
` ``{.tex}
\crfnmsetup[default]{collapsable?=yes}
\crfnmsetup[note]{collapsable?=no}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultCollapsable{yes}
\def\crfnmNoteCollapsable{no}
` ``
Thus, a reference to consecutive notes is formatted like _nn. –
Thus, unless you change that, a reference to consecutive notes
is formatted like “nn. –
Ranges are not accepted in the argument of ` \crossrefenum` for non-collapsable types.
This extends to double types that include a non-collapsable type
(such as ` pagenote` in the default configuration).
(such as ` pagenote` in the built-in configuration).
### Double types
Two subtypes in a double type (e.g. pagenote`)
are separated by ` \crfnmDefaultSubtypesSep`. Default :
You can set like this the separator between the two values in a double reference
(e.g. pagenote` reference) :
` ``{.tex}
\crfnmsetup[default]{subtypes separator={, }}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultSubtypesSep{, }
@ -146,51 +233,96 @@ are separated by `\crfnmDefaultSubtypesSep`. Default:
When more than one reference is cited in an enumeration,
you may not want the first prefix to be repeated every time
(e.g. could prefer “pp. ver “p.
In that case, set ` \crfnmDefaultPrintFirstPrefix` to ` onc e`.
Default is:
(e.g. may prefer “pp. t o “p.
In this case, set ` print prefix of first subtyp e`
or ` \crfnmDefaultPrintFirstPrefix` to ` once`.
Otherwise you will get:
` ``{.tex}
\crfnmsetup[default]{
print prefix of first subtype = always
}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultPrintFirstPrefix{always}
` ``
If you want to format the second part of the referenc e in a special way (e.g.
u se ` \crfnmDefaultFormatInSecond`,
which takes one argument which corresponds to the reference number and all its affixes .
Default is:
If you want to format the second subtyp e in a special way (e.g.
set the key ` formatting when second subtype` either to ` {}` (no formatting)
or to a macro which will take the reference number and all its affixes as its only argument (e.g. \textsuperscript`) .
Alternatively, you can define ` \crfnmDefaultFormatInSecond` with one argument.
What ` \crossrefenum` comes with is:
` ``{.tex}
\crfnmsetup[default]{formatting when second subtype = {}}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultFormatInSecond#1{#1}
` ``
If you don't want any prefix to be printed in the second term of a double reference,
set ` \crfnmDefaultP rintP refixInSecond` to ` no` (default is yes).
F or instance:
set ` p rint p refix when second subtype?`
or ` \crfnmDefaultPrintPrefixInSecond` to ` no` (built-in: yes).
Here is how you can print the line number in superscript
when it comes after the corresponding page number:
` ``{.tex}
\crfnmsetup[edline]{
formatting when second subtype = \textsuperscript,
print prefix when second subtype? = no
}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmEdlineFormatInSecond#1{\textsuperscript{#1}}
\def\crfnmEdlinePrintPrefixInSecond{no}
\crossrefenum[edpageline]{{mylabel}}
` ``
` \noindentation`{=context} may return “p. \crossrefenum[edline]{{mylabel}}` would return “l.
For the second part of such an enumeration (e.g. ,
you can specify a specific delimiter
and a specific string to be printed before the last reference:
for instance, you may want to use the word “and”
before the last note number if the reference type is a simple one (` note`),
After that, ` \crossrefenum[edpageline]{mylabel}` may return “p. ,
whereas ` \crossrefenum[edline]{mylabel}` would return “l.
You can specify a specific delimiter for the second part of double references and a specific string
to be printed before the last reference of the second sub type in a double reference
(e.g.
For instance, you may want to use the word “and”
before the last note number if the reference type is a simple one (` note`)
and a comma if it is comes in second in a double reference (e.g. pagenote`).
To achieve this, you should redefine ` \crfnmDefaultEnumDelimInSecond`
and ` \crfnmDefaultB efo reLastInSecond `.
By default, these macros fall back respectively
o n ` \crfnmDefaultEnumDelim` and ` \crfnmDefaultBeforeLastInEnum`.
To achieve this, you can set ` delimiter when second subtype` (= ` \crfnmDefaultEnumDelimInSecond`)
and ` before last r efe rence when second subtype `
(= \crfnmDefaultBeforeLastInSecond`).
I n the built-in configuration, there is no difference between a simple type used alone
and the same simple type taken as the second subtype of a double type,
but we could imagine the following:
` ``{.tex}
\crfnmsetup[note]{
delimiter = {; },
before last reference = { and },
delimiter when second subtype = {, },
before last reference when second subtype = {, }
}
\crossrefenum[note]{lbl1, lbl2, lbl3}
= \crossrefenum[pagenote]{lbl1, lbl2, lbl3}
` ``
` \noindentation`{=context} which may yield: “n.
When citing a range, the two parts of the reference can
either be split (e.g. –
be either split (e.g. –
or grouped (“p. – –
This is controlled via ` \crfnmDefaultGroupSubtypes`, which can be set to ` yes` or ` no`.
T his works only with [collapsable types](#collapsable-types) .
Default is :
This is controlled via ` group subtypes?` (= \crfnmDefaultGroupSubtypes`) ,
w hich can be set to ` yes` or ` no` .
This works only with [collapsable types](#collapsable-types) :
` ``{.tex}
\crfnmsetup[default]{group subtypes? = no}
` ``
` \noindentation`{=context} which amounts to:
` ``{.tex}
\def\crfnmDefaultGroupSubtypes{no}
@ -200,39 +332,29 @@ To know if a reference to “p.
_crossrefenum_ needs to know if the lineation is
continuous (in this case, these lines are consecutive)
or per page (they are not, so they should not be merged).
You can set accordingly
` \crfnmDefaultNumberingContinuousAcrossDocument`[^line-numbering] to ` yes` (default) or ` no`.
You can set accordingly ` continuous numbering?`
(= ``) [^line-numbering]
to ` yes` (built-in) or ` no`.
Note that _crossrefenum_ cannot merge a reference
to the last line of a page and the first line of the following page
if the lineation is not continuous.
[^line-numbering]: In this case, you could set more specifically
` \crfnmLineNumberingContinuousAcrossDocument`
or ` \crfnmEdlineNumberingContinuousAcrossDocument`:
see [the following subsection](#specialize-config-macros) .
By default, the number of the first subtype in the name of the double type
(e.g. “page” in “pagenote”) is always displayed first.
If you want to change this, set ` \crfnmDefaultOrder` to ` inverted` (defaults to ` normal`).
### Specific values for given types {#specialize-config-macros}
If you want to override some of these macros for a specific type,
simply replace ` Default` in its name with the (capitalized) name of the type
(e.g. \def\crfnmPageEnumDelim{; }`).
Setting one of these macros to ` \relax` will cause ` \crossrefenum`
to use the corresponding default macro instead.
If you want a specific macro to be set to nothing,
use an empty group (e.g. \def\crfnmPageEnumDelim{}`).
or ` \crfnmEdlineNumberingContinuousAcrossDocument`
or use ` \crfnmsetup` with ` [line]` and ` [edline]` .
In the built-in configuration, the order of the subtypes in the name of a subtype
(e.g. “page” and “note” in “pagenote”) determines by default
the order in which they are printed (e.g.
If you want to change this, set ` order` (= \crfnmDefaultOrder`) to ` inverted` (built-in: ` normal`).
## How to extend crossrefenum with other types and formats {#extending}
Adding support for new types consists in defining the related macros in your preamble.
Here is a commented example that would add support for references to lines in ConTeXt
if this feature were not already included in _crossrefenum_.
We suppose that the labels are inserted in the document using the standard ConTeXt macros,
I suppose that the labels are inserted in the document using the standard ConTeXt macros,
i.e. \someline` for line references and ` \pagereference` for page references.
` ``{.tex}
@ -269,13 +391,14 @@ i.e.
\def\crfnm@getLineNumber#1{\directlua{get_raw_ref_number('lr:b:#1', 'linenumber')}}
% Define all specific configuration options in the regular way.
%% Required
\def\crfnmLine{l.~}
\def\crfnmLines{ll.~}
% Instead of the following, you can use \crfnmsetup.
` ``
` ``{.tex}
%% Required
\def\crfnmLine{l.~}
\def\crfnmLines{ll.~}
%% If it differs from the defaults.
\def\crfnmLineCollapsable{yes}
\def\crfnmLineBeforeLastInSecond{, }
Bastien Dumont