bdumont/crossrefenum
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added a summary of the macros and config keys/macros

Browse Source
This commit is contained in:
Bastien Dumont
2025-08-07 16:37:17 +02:00
parent 58deb3f384
commit e9ed29f53b
5 changed files with 200 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Makefile
View File

@ -3,7 +3,8 @@ crossrefenum.pdf: crossrefenum-doc.tex
crossrefenum-doc.tex: crossrefenum.md ../CHANGELOG.md \ crossrefenum-doc.tex: crossrefenum.md ../CHANGELOG.md \
TEMPLATE_crossrefenum.context fixes.lua TEMPLATE_crossrefenum.context fixes.lua
pandoc -s -o $@ -t context \ pandoc -s -o $@ -t context-smart \
--template=TEMPLATE_crossrefenum.context \ --template=TEMPLATE_crossrefenum.context \
-L fixes.lua \ -L fixes.lua \
crossrefenum.md ../CHANGELOG.md crossrefenum.md ../CHANGELOG.md
sh ./microfixes-doc.sh $@

4
doc/TEMPLATE_crossrefenum.context
View File

@ -23,7 +23,7 @@ $endif$
\setupbodyfontenvironment[default][em=italic] \setupbodyfontenvironment[default][em=italic]
\definefontfamily[mainface][rm][cochineal] \definefontfamily[mainface][rm][cochineal]
\definefontfamily[mainface][ss][libertinussans] \definefontfamily[mainface][ss][libertinussans]
\definefontfamily[mainface][tt][nimbusmonops][features=none] \definefontfamily[mainface][tt][dejavusansmono][features=none, rscale=0.75]
\setupbodyfont[mainface,12pt] \setupbodyfont[mainface,12pt]
\setuptype[lines=no] \setuptype[lines=no]
@ -39,7 +39,7 @@ $endif$
\setuppagenumbering[location=] % Pour que le numéro de page n'apparaisse pas en haut au milieu \setuppagenumbering[location=] % Pour que le numéro de page n'apparaisse pas en haut au milieu
\setupheader[text][leftstyle=\em] \setupheader[text][leftstyle=\em]
\setupheadertexts[section][pagenumber] \setupheadertexts[section][pagenumber]
\setupfootertexts$if(toc)$[{\inframed{\goto{Table of contents}[page(3)]}}]$endif$[{\inframed{\goto{Jump to previous page}[PreviousJump]}}] \setupfootertexts$if(toc)$[{\inframed{\goto{Table of contents}[page(3)]}}]$endif$[{\inframed{\goto{Summary}[page(7)]}}]
\setupbackend[ \setupbackend[
format={pdf/a-1a:2005}, format={pdf/a-1a:2005},

126
doc/crossrefenum.md
View File

@ -49,7 +49,101 @@ you can do:
must be called after _nameref_ if you use _hyperref_`\kern1.5pt`{=context}); must be called after _nameref_ if you use _hyperref_`\kern1.5pt`{=context});
* `\usemodule[crossrefenum]` (ConTeXt). * `\usemodule[crossrefenum]` (ConTeXt).
## Basic invocation ## Summary {#summary}
* [`\crossrefenum`](#macro-crossrefenum): the main macro
* [`\crfnmsetup`](#crfnmsetup-macro): configuration macro (default of per type)
```{=context}
\vskip\bigskipamount
```
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|**Configuration |**Configuration macro (with `\def`)** |**Meaning** |**Example** |**Page** |
|key (with | | | | |
|`\crfnmsetup`)** | | | | |
+=================+===============================================+=====================+==============+==============================+
|`<type>` _is a single type_ |`page` |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`sg` |`\crfnm<type>` |Singular prefix |`{p. }` |`\at[prefixes]`{=context} |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`pl` |`\crfnm<type>s` |Plural prefix |`{pp. }` |`\at[prefixes]`{=context} |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`delimiter` |`\crfnm<type>EnumDelim` |Delimiter between |`{, }` |`\at[delimiters]`{=context} |
| | |references | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`before last |`\crfnm<type>BeforeLastInEnum` |Delimiter before the |`{ and }` |`\at[delimiters]`{=context} |
|reference` | |last reference | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`range separator`|`\crfnm<type>RangeSep` |Separator between the|`{\tt |`\at[range-sep]`{=context} |
| | |two values in a range|`{=context} – | |
| | | |`}`{=context} | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`collapsable?` |`\crfnm<type>Collapsable` |Should consecutive |`yes` or `no` |`\at[collapsable]`{=context} |
| | |numbers (e.g. 2, 3, | | |
| | |4) be merged into a | | |
| | |range? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`<type>` _is a double type_ |`pagenote` |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`subtypes |`\crfnm<type>SubtypesSep` |Separator between the|`{, }` |`\at[subtypes-sep]`{=context} |
|separator` | |two types of | | |
| | |references in a | | |
| | |double reference | | |
| | |(e.g. between the | | |
| | |page and note numbers| | |
| | |in a reference to a | | |
| | |note including the | | |
| | |page number) | | |
| | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`print prefix of |`\crfnm<type>PrintFirstPrefix` |Should the numbers of|`always` or |`\at[fst-pref-dlb]`{=context} |
|first subtype` | |the first subtype be |`once` | |
| | |prefixed always or | | |
| | |only for the first | | |
| | |reference in an | | |
| | |enumeration? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`group subtypes?`|`\crfnm<type>GroupSubtypes` |Sould all the values |`yes` or `no` |`\at[group-subt]`{=context} |
| | |for each subtype be | | |
| | |printed separately? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`order` |`\crfnm<type>Order` |Whether the subtypes |`normal` or |`\at[order]`{=context} |
| | |are printed in the |`inverted` | |
| | |same order as in the | | |
| | |name of the double | | |
| | |type | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`<type>` _is a single type; the following options apply when it is used as the second |`page` |
|subtype of a double type_ | |
| | |
| | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`formatting when |`\crfnm<type>FormatInSecond` |`{}` or a macro that |`\textbf` |`\at[fmt-sec-subt]`{=context} |
|second subtype` | |takes the prefixes | | |
| | |and numbers as its | | |
| | |argument | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`print prefix |`\crfnm<type>PrintPrefixInSecond` |Should the prefix be |`yes` or `no` |`\at[rep-pref-dbl]`{=context} |
|when second | |printed? | | |
|subtype?` | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`delimiter when |`\crfnm<type>EnumDelimInSecond` |Delimiter between |`{, }` |`\at[delim-sec-dbl]`{=context}|
|second subtype` | |references | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`before last |`\crfnm<type>BeforeLastInSecond` |Delimiter before the |`{ and }` |`\at[delim-sec-dbl]`{=context}|
|reference when | |last reference | | |
|second subtype` | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`continuous |`\crfnm<type>NumberingContinuousAcrossDocument`|Is the numbering for |`yes` or `no` |`\at[numb-contin]`{=context} |
|numbering?` | |this type continuous | | |
| | |(i.e. not reset at | | |
| | |every | | |
| | |page/chapter/etc.)? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
## Basic invocation {#macro-crossrefenum}
The macro `\crossrefenum` has the following syntax: The macro `\crossrefenum` has the following syntax:
@ -86,7 +180,7 @@ The same invocations with the group-based syntax:
* `\crossrefenum{{lblone}{lbltwo}{lblthree}}` * `\crossrefenum{{lblone}{lbltwo}{lblthree}}`
* `\crossrefenum{{only-one}}` (even if the enumeration is limited to one item, it can be inside its own group) * `\crossrefenum{{only-one}}` (even if the enumeration is limited to one item, it can be inside its own group)
## Customization ## Customization {#crfnmsetup-macro}
There are two configuration interfaces: There are two configuration interfaces:
one based on key-value lists, the other on (re)defining macros. one based on key-value lists, the other on (re)defining macros.
@ -141,7 +235,7 @@ correspond to the built-in configuration.
### Prefixes, delimiters and separators ### Prefixes, delimiters and separators
You can define the singular and plural prefixes You can define the [singular and plural prefixes]{#prefixes}
printed before the value of the reference like this: printed before the value of the reference like this:
```{.tex} ```{.tex}
@ -166,7 +260,7 @@ printed before the value of the reference like this:
`\noindentation`{=context} (it would have been more accurate to write `\noindentation`{=context} (it would have been more accurate to write
`\crfnmsetup[edpage]{sg=\crfnmPage, pl=\crfnmPages}`). `\crfnmsetup[edpage]{sg=\crfnmPage, pl=\crfnmPages}`).
The delimiters printed respectively between the successive references in an enumeration The [delimiters]{#delimiters} printed respectively between the successive references in an enumeration
and before the last one are set so: and before the last one are set so:
```{.tex} ```{.tex}
@ -182,7 +276,7 @@ and before the last one are set so:
\def\crfnmDefaultBeforeLastInEnum{ and } \def\crfnmDefaultBeforeLastInEnum{ and }
``` ```
The separator in a range is set like this: The [separator in a range]{#range-sep} is set like this:
```{.tex} ```{.tex}
\crfnmsetup[default]{range separator = –} \crfnmsetup[default]{range separator = –}
@ -193,7 +287,7 @@ The separator in a range is set like this:
\def\crfnmDefaultRangeSep{–} \def\crfnmDefaultRangeSep{–}
``` ```
### Collapsable and non-collapsable types {#collapsable-types} ### Collapsable and non-collapsable types {#collapsable}
The configuration option `collapsable?` and The configuration option `collapsable?` and
the macro `\crfnmDefaultCollapsable` define if ranges are allowed. the macro `\crfnmDefaultCollapsable` define if ranges are allowed.
@ -219,7 +313,7 @@ This extends to double types that include a non-collapsable type
### Double types ### Double types
You can set like this the separator between the two values in a double reference You can set like this [the separator between the two values in a double reference]{#subtypes-sep}
(e.g. the page and the note numbers in a `pagenote` reference): (e.g. the page and the note numbers in a `pagenote` reference):
```{.tex} ```{.tex}
@ -232,7 +326,7 @@ You can set like this the separator between the two values in a double reference
``` ```
When more than one reference is cited in an enumeration, When more than one reference is cited in an enumeration,
you may not want the first prefix to be repeated every time [you may not want the first prefix to be repeated every time]{#fst-pref-dbl}
(e.g. you may prefer “pp. 5, n. 2; 7, n. 4” to “p. 5, n. 2; p. 7, n. 4”). (e.g. you may prefer “pp. 5, n. 2; 7, n. 4” to “p. 5, n. 2; p. 7, n. 4”).
In this case, set `print prefix of first subtype` In this case, set `print prefix of first subtype`
or `\crfnmDefaultPrintFirstPrefix` to `once`. or `\crfnmDefaultPrintFirstPrefix` to `once`.
@ -249,7 +343,7 @@ Otherwise you will get:
\def\crfnmDefaultPrintFirstPrefix{always} \def\crfnmDefaultPrintFirstPrefix{always}
``` ```
If you want to format the second subtype in a special way (e.g. in superscript), If you want to [format the second subtype]{#fmt-sec-subt} in a special way (e.g. in superscript),
set the key `formatting when second subtype` either to `{}` (no formatting) 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`). 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. Alternatively, you can define `\crfnmDefaultFormatInSecond` with one argument.
@ -264,7 +358,7 @@ What `\crossrefenum` comes with is:
\def\crfnmDefaultFormatInSecond#1{#1} \def\crfnmDefaultFormatInSecond#1{#1}
``` ```
If you don't want any prefix to be printed in the second term of a double reference, [If you don't want any prefix to be printed in the second term of a double reference]{#rep-pref-dbl},
set `print prefix when second subtype?` set `print prefix when second subtype?`
or `\crfnmDefaultPrintPrefixInSecond` to `no` (built-in: yes). or `\crfnmDefaultPrintPrefixInSecond` to `no` (built-in: yes).
@ -287,8 +381,8 @@ when it comes after the corresponding page number:
After that, `\crossrefenum[edpageline]{mylabel}` may return “p. 5^10^”, After that, `\crossrefenum[edpageline]{mylabel}` may return “p. 5^10^”,
whereas `\crossrefenum[edline]{mylabel}` would return “l. 10”. whereas `\crossrefenum[edline]{mylabel}` would return “l. 10”.
You can specify a specific delimiter for the second part of double references and a specific string You can specify a [specific delimiter for the second part of double references]{#delim-sec-dbl}
to be printed before the last reference of the second subtype in a double reference and a specific string to be printed before the last reference of the second subtype in a double reference
(e.g. the last reference to a line in “p. 5, l. 10, 13, 16”, which is “16”). (e.g. the last reference to a line in “p. 5, l. 10, 13, 16”, which is “16”).
For instance, you may want to use the word “and” For instance, you may want to use the word “and”
before the last note number if the reference type is a simple one (`note`) before the last note number if the reference type is a simple one (`note`)
@ -312,12 +406,12 @@ but we could imagine the following:
``` ```
`\noindentation`{=context} which may yield: “n. 1; 2 and 5 = p. 8, n. 1, 2, 5”. `\noindentation`{=context} which may yield: “n. 1; 2 and 5 = p. 8, n. 1, 2, 5”.
When citing a range, the two parts of the reference can [When citing a range, the two parts of the reference]{#group-subt} can
be either split (e.g. “p. 5, l. 3 – p. 7, l. 44”) be either split (e.g. “p. 5, l. 3 – p. 7, l. 44”)
or grouped (“p. 5–7, l. 3–44”). or grouped (“p. 5–7, l. 3–44”).
This is controlled via `group subtypes?` (= `\crfnmDefaultGroupSubtypes`), This is controlled via `group subtypes?` (= `\crfnmDefaultGroupSubtypes`),
which can be set to `yes` or `no`. which can be set to `yes` or `no`.
This works only with [collapsable types](#collapsable-types): This works only with [collapsable types](#collapsable):
```{.tex} ```{.tex}
\crfnmsetup[default]{group subtypes? = no} \crfnmsetup[default]{group subtypes? = no}
@ -330,7 +424,7 @@ This works only with [collapsable types](#collapsable-types):
To know if a reference to “p. 6, l. 34” should be merged with “p. 7, l. 35”, To know if a reference to “p. 6, l. 34” should be merged with “p. 7, l. 35”,
_crossrefenum_ needs to know if the lineation is _crossrefenum_ needs to know if the lineation is
continuous (in this case, these lines are consecutive) [continuous]{#numb-contin} (in this case, these lines are consecutive)
or per page (they are not, so they should not be merged). or per page (they are not, so they should not be merged).
You can set accordingly `continuous numbering?` You can set accordingly `continuous numbering?`
(= `\crfnmDefaultNumberingContinuousAcrossDocument`)[^line-numbering] (= `\crfnmDefaultNumberingContinuousAcrossDocument`)[^line-numbering]
@ -344,7 +438,7 @@ if the lineation is not continuous.
or `\crfnmEdlineNumberingContinuousAcrossDocument` or `\crfnmEdlineNumberingContinuousAcrossDocument`
or use `\crfnmsetup` with `[line]` and `[edline]`. or use `\crfnmsetup` with `[line]` and `[edline]`.
In the built-in configuration, the order of the subtypes in the name of a subtype In the built-in configuration, the [order of the subtypes]{#order} in the name of a subtype
(e.g. “page” and “note” in “pagenote”) determines by default (e.g. “page” and “note” in “pagenote”) determines by default
the order in which they are printed (e.g. “p. 6, n. 2” instead of “n. 2, p. 6”). the order in which they are printed (e.g. “p. 6, n. 2” instead of “n. 2, p. 6”).
If you want to change this, set `order` (= `\crfnmDefaultOrder`) to `inverted` (built-in: `normal`). If you want to change this, set `order` (= `\crfnmDefaultOrder`) to `inverted` (built-in: `normal`).

2
doc/fixes.lua
View File

@ -5,10 +5,12 @@ local function set_break_points(code)
local broken_code = {} local broken_code = {}
for a, b in string.gmatch(raw_code, '([^a-zA-Z\\]?)([A-Z\\]?[a-z.]*)') do for a, b in string.gmatch(raw_code, '([^a-zA-Z\\]?)([A-Z\\]?[a-z.]*)') do
if a ~= '' then if a ~= '' then
a = string.gsub(a, ' ', ' ') -- the leading/trailing spaces get gobbled
table.insert(broken_code, ZERO_WD_SP) table.insert(broken_code, ZERO_WD_SP)
table.insert(broken_code, pandoc.Code(a)) table.insert(broken_code, pandoc.Code(a))
end end
if b ~= '' then if b ~= '' then
b = string.gsub(b, ' ', ' ')
table.insert(broken_code, ZERO_WD_SP) table.insert(broken_code, ZERO_WD_SP)
table.insert(broken_code, pandoc.Code(b)) table.insert(broken_code, pandoc.Code(b))
end end

83
doc/table-config.txt Normal file
View File

@ -0,0 +1,83 @@
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|**Configuration |**Configuration macro (with `\def`)** |**Meaning** |**Example** |**Page** |
|key (with | | | | |
|`\crfnmsetup`)** | | | | |
+=================+===============================================+=====================+==============+==============================+
|`<type>` _is a single type_ |`page` |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`sg` |`\crfnm<type>` |Singular prefix |`{p. }` |`\at[prefixes]`{=context} |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`pl` |`\crfnm<type>s` |Plural prefix |`{pp. }` |`\at[prefixes]`{=context} |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`delimiter` |`\crfnm<type>EnumDelim` |Delimiter between |`{, }` |`\at[delimiters]`{=context} |
| | |references | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`before last |`\crfnm<type>BeforeLastInEnum` |Delimiter before the |`{ and }` |`\at[delimiters]`{=context} |
|reference` | |last reference | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`range separator`|`\crfnm<type>RangeSep` |Separator between the|`{\tt |`\at[range-sep]`{=context} |
| | |two values in a range|`{=context} – | |
| | | |`}`{=context} | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`collapsable?` |`\crfnm<type>Collapsable` |Should consecutive |`yes` or `no` |`\at[collapsable]`{=context} |
| | |numbers (e.g. 2, 3, | | |
| | |4) be merged into a | | |
| | |range? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`<type>` _is a double type_ |`pagenote` |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`subtypes |`\crfnm<type>SubtypesSep` |Separator between the|`{, }` |`\at[subtypes-sep]`{=context} |
|separator` | |two types of | | |
| | |references in a | | |
| | |double reference | | |
| | |(e.g. between the | | |
| | |page and note numbers| | |
| | |in a reference to a | | |
| | |note including the | | |
| | |page number) | | |
| | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`print prefix of |`\crfnm<type>PrintFirstPrefix` |Should the numbers of|`always` or |`\at[fst-pref-dlb]`{=context} |
|first subtype` | |the first subtype be |`once` | |
| | |prefixed always or | | |
| | |only for the first | | |
| | |reference in an | | |
| | |enumeration? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`group subtypes?`|`\crfnm<type>GroupSubtypes` |Sould all the values |`yes` or `no` |`\at[group-subt]`{=context} |
| | |for each subtype be | | |
| | |printed separately? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`order` |`\crfnm<type>Order` |Whether the subtypes |`normal` or |`\at[order]`{=context} |
| | |are printed in the |`inverted` | |
| | |same order as in the | | |
| | |name of the double | | |
| | |type | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`<type>` _is a single type; the following options apply when it is used as the second |`page` |
|subtype of a double type_ | |
| | |
| | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`formatting when |`\crfnm<type>FormatInSecond` |`{}` or a macro that |`\textbf` |`\at[fmt-sec-subt]`{=context} |
|second subtype` | |takes the prefixes | | |
| | |and numbers as its | | |
| | |argument | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`print prefix |`\crfnm<type>PrintPrefixInSecond` |Should the prefix be |`yes` or `no` |`\at[rep-pref-dbl]`{=context} |
|when second | |printed? | | |
|subtype?` | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`delimiter when |`\crfnm<type>EnumDelimInSecond` |Delimiter between |`{, }` |`\at[delim-sec-dbl]`{=context}|
|second subtype` | |references | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`before last |`\crfnm<type>BeforeLastInSecond` |Delimiter before the |`{ and }` |`\at[delim-sec-dbl]`{=context}|
|reference when | |last reference | | |
|second subtype` | | | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+
|`continuous |`\crfnm<type>NumberingContinuousAcrossDocument`|Is the numbering for |`yes` or `no` |`\at[numb-contin]`{=context} |
|numbering?` | |this type continuous | | |
| | |(i.e. not reset at | | |
| | |every | | |
| | |page/chapter/etc.)? | | |
+-----------------+-----------------------------------------------+---------------------+--------------+------------------------------+