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 \
TEMPLATE_crossrefenum.context fixes.lua
pandoc -s -o $@ -t context \
pandoc -s -o $@ -t context-smart \
--template=TEMPLATE_crossrefenum.context \
-L fixes.lua \
crossrefenum.md ../CHANGELOG.md
sh ./microfixes-doc.sh $@

4
doc/TEMPLATE_crossrefenum.context
View File

@ -23,7 +23,7 @@ $endif$
\setupbodyfontenvironment[default][em=italic]
\definefontfamily[mainface][rm][cochineal]
\definefontfamily[mainface][ss][libertinussans]
\definefontfamily[mainface][tt][nimbusmonops][features=none]
\definefontfamily[mainface][tt][dejavusansmono][features=none, rscale=0.75]
\setupbodyfont[mainface,12pt]
\setuptype[lines=no]
@ -39,7 +39,7 @@ $endif$
\setuppagenumbering[location=] % Pour que le numéro de page n'apparaisse pas en haut au milieu
\setupheader[text][leftstyle=\em]
\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[
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});
* `\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:
@ -86,7 +180,7 @@ The same invocations with the group-based syntax:
* `\crossrefenum{{lblone}{lbltwo}{lblthree}}`
* `\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:
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
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:
```{.tex}
@ -166,7 +260,7 @@ printed before the value of the reference like this:
`\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
The [delimiters]{#delimiters} printed respectively between the successive references in an enumeration
and before the last one are set so:
```{.tex}
@ -182,7 +276,7 @@ and before the last one are set so:
\def\crfnmDefaultBeforeLastInEnum{ and }
```
The separator in a range is set like this:
The [separator in a range]{#range-sep} is set like this:
```{.tex}
\crfnmsetup[default]{range separator = –}
@ -193,7 +287,7 @@ The separator in a range is set like this:
\def\crfnmDefaultRangeSep{–}
```
### Collapsable and non-collapsable types {#collapsable-types}
### Collapsable and non-collapsable types {#collapsable}
The configuration option `collapsable?` and
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
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):
```{.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,
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”).
In this case, set `print prefix of first subtype`
or `\crfnmDefaultPrintFirstPrefix` to `once`.
@ -249,7 +343,7 @@ Otherwise you will get:
\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)
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.
@ -264,7 +358,7 @@ What `\crossrefenum` comes with is:
\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?`
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^”,
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
to be printed before the last reference of the second subtype in a double reference
You can specify a [specific delimiter for the second part of double references]{#delim-sec-dbl}
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”).
For instance, you may want to use the word “and”
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”.
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”)
or grouped (“p. 5–7, l. 3–44”).
This is controlled via `group subtypes?` (= `\crfnmDefaultGroupSubtypes`),
which can be set to `yes` or `no`.
This works only with [collapsable types](#collapsable-types):
This works only with [collapsable types](#collapsable):
```{.tex}
\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”,
_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).
You can set accordingly `continuous numbering?`
(= `\crfnmDefaultNumberingContinuousAcrossDocument`)[^line-numbering]
@ -344,7 +438,7 @@ if the lineation is not continuous.
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
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
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`).

4
doc/fixes.lua
View File

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