bdumont/pandoc-lua-filters
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up and reformat the README, removing references to text-extrefs

Browse Source
This commit is contained in:
Bastien Dumont 2022-11-05 21:05:49 +01:00
parent e868420bf6
commit ac7abe5ef0
1 changed files with 123 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
README.md
View File

@ -1,9 +1,10 @@
# text-crossrefs: getting references to page and note numbers in Pandoc
# text-crossrefs: cross-references to arbitrary portions of text in Pandoc
This filters aims at extending Pandoc's cross-referencing
capacities by enabling automatic references to any piece of text
by either its page or, whenever it applies, its note number. It
currently supports the following target formats:
This filter extends Pandoc's cross-referencing abilities
with references to any portion of text
by its page number, its note number (when applicable)
or an arbitrary reference type (with ConTeXt or LaTeX output).
It currently supports the following output formats:
* context
* docx
@ -11,54 +12,80 @@ currently supports the following target formats:
* odt
* opendocument
It does not permit to refer to references in other files: if you want to do this, use text-extrefs.
## Format-specific preliminary notices
### DOCX and ODT/Opendocument
When opening for the first time a file produced by Pandoc with text-crossrefs, you probably will have to refresh the fields in order to get the correct values. In LibreOffice, press `F9`; in Word, a dialog box should appear when the file opens.
When opening for the first time a file produced by Pandoc with _text-crossrefs_,
you should have to refresh the fields in order to get the correct values.
In LibreOffice, press `F9`; in Word, a dialog box should appear when the file opens.
### TeX-based formats
All references are wrapped in a macro named `\tcrfenum`. It has two optional arguments: the first one is the reference type, the second specifies whether the prefix (e.g. “p. ”) should be printed or not (can be set to `withprefix`, `noprefix`, `yes` or `no`). The default values for these arguments should match those of `tcrf-default-reftype` and `tcrf-default-prefixref` (resp. `page` and `yes`, i.e. `withprefix`). The mandatory argument of `\tcrfenum` is a group containing a list of groups. Each of them contain a reference (either a single reference or a range). Here are some valid invocations:
All references are wrapped in a macro named `\tcrfenum`.
It has two optional arguments:
the first one is the reference type,
the second indicates whether the prefix (e.g. “p. ”) should be printed or not
(can be set to `withprefix`, `noprefix`, `yes` or `no`).
The default values for these arguments should match
those of `tcrf-default-reftype` and `tcrf-default-prefixref`
(resp. `page` and `yes`, i.e. `withprefix`).
The mandatory argument of `\tcrfenum` is a group enclosing one or more groups.
Each of them contain a reference (either a single reference or a range).
* \tcrfenum\[note\]\[withprefix\]{{lblone}{lbltwo}{lblthree}}
* \tcrfenum\[page\]\[noprefix\]{{lblone}{lbltwo}{lblthree}}
* \tcrfenum\[noprefix\]{{lblone}{lbltwo}{lblthree}} (the first argument defaults to `page`)
* \tcrfenum{{lblone}{lbltwo}{lblthree}} (the second argument defaults to `withprefix`)
* \tcrfenum{{only-one}} (even if the enumeration is limited to one item, it must be inside its own group)
* \tcrfenum{{lblone to lbltwo}{lblthree}} (the first reference points to a range)
Here are some valid invocations:
It is up to you to define `\tcrfenum` in your preamble. If your target format is LaTeX, it should be possible to define it as a wrapper for the `\zcref` macro provided by [the zref-clever package](https://ctan.org/pkg/zref-clever). Alternatively, you can use [my implementation](TODO), which supports ConTeXt, LaTeX and other formats. Here are some hints about the implementation:
* `\tcrfenum[note][withprefix]{{lblone}{lbltwo}{lblthree}}`
* `\tcrfenum[page][noprefix]{{lblone}{lbltwo}{lblthree}}`
* `\tcrfenum[noprefix]{{lblone}{lbltwo}{lblthree}}` (the first argument defaults to `page`)
* `\tcrfenum{{lblone}{lbltwo}{lblthree}}` (the second argument defaults to `withprefix`)
* `\tcrfenum{{only-one}}` (even if the enumeration is limited to one item, it must be in a group)
* `\tcrfenum{{lblone to lbltwo}{lblthree}}` (the first reference points to a range)
* [The `\tcrfenum` macro is supposed to output the numbers along with the prefixes and delimiters (e.g. “p. ” and “–”)]{#prefixes-tex};
* In ConTeXt, there is no way to retrieve the note number from a `\reference` or a `\pagereference` contained in the note as is customary in LaTeX. to work around this, footnotes are labelled automatically with the first identifier attached to a span in the note prefixed with `note:`. Contrary to the ConTeXt syntax, this label is placed _after_ the footnote content, which implies redefining the `\footnote` macro. If your template includes the `header-includes` metadata variable like in the default template, this redefinition will happen automatically. Otherwise, you can copy-paste the following code in your preamble:
It is up to you to define `\tcrfenum` in your preamble.
If your target format is LaTeX, it should be possible to define it as a wrapper
for the `\zcref` macro provided by [the zref-clever package](https://ctan.org/pkg/zref-clever).
Alternatively, you can use [my implementation](TODO),
which currently supports ConTeXt and LaTeX.
Here are some hints about the implementation of the `\tcrfenum` macro:
``` {=tex}
\catcode`\@=11
\let\origfootnote\footnote
\def\footnote#1#2{
\def\tcrf@secondArg{#2}%
\ifx\tcrf@secondArg\tcrf@bracket
\def\tcrf@todo{\tcrf@footnote@withlabel{#1}#2} %
\else
\def\tcrf@todo{\origfootnote{#1}#2}%
\fi
\tcrf@todo
}
\def\tcrf@bracket{[}
\def\tcrf@footnote@withlabel#1[#2]{\origfootnote[#2]{#1}}
\catcode`\@=13
* [The `\tcrfenum` macro is supposed to output non only the numbers,
but also the prefixes and delimiters (e.g. “p. ” and “–”)]{#prefixes-tex};
* In ConTeXt, there is no way to retrieve the note number
from a `\reference` or a `\pagereference` contained in the note
as one would from a `\label` in LaTeX.
To work around this, footnotes are labelled automatically with `note:`
followed by the first identifier attached to a span in the note.
Contrary to the ConTeXt syntax, this label is placed _after_ the footnote content,
so the `\footnote` macro has to be redefined.
If your template includes the `header-includes` metadata variable like the default one does,
this redefinition will happen automatically.
Otherwise, you can copy-paste the following code in your preamble:
```
``` {=tex}
\catcode`\@=11
\let\origfootnote\footnote
\def\footnote#1#2{
\def\tcrf@secondArg{#2}%
\ifx\tcrf@secondArg\tcrf@bracket
\def\tcrf@todo{\tcrf@footnote@withlabel{#1}#2} %
\else
\def\tcrf@todo{\origfootnote{#1}#2}%
\fi
\tcrf@todo
}
\def\tcrf@bracket{[}
\def\tcrf@footnote@withlabel#1[#2]{\origfootnote[#2]{#1}}
\catcode`\@=13
```
## Usage
### Basics
Mark the span of text you want to refer to later with an
identifier composed of alphanumeric characters, periods, colons, underscores and hyphens:
Mark the span of text you want to refer to later
with an identifier composed of alphanumeric characters, periods, colons, underscores or hyphens:
``` markdown
Émile Gaboriau published [_L'Affaire Lerouge_ in
@ -69,10 +96,11 @@ identifier composed of alphanumeric characters, periods, colons, underscores and
[It was very popular.]{#reception}
```
You can refer to it using another span with class `ref` containing
the target's identifier. If the targetted span is part of a
footnote, you can refer to it either by page or by note number according to
the value of the `reftype` attribute (defaults to `page`). For instance, this:
To refer to it, write another span with class `tcrf` containing the target's identifier.
If the span you are referring to is part of a footnote,
you can refer to it either by page or note number
according to the value of the `reftype` attribute (defaults to `page`).
For instance, this:
``` markdown
See [publication]{.tcrf} for the publication date. I gave my
@ -87,21 +115,23 @@ my thoughts about it in \tcrfenum[note]{{my-evaluation}},
\tcrfenum{{my-evaluation}}.
```
If you want to give a reference by note and page number like in the example above, you can also use the following shorthand:
If you want to give a reference by note _and_ page number like in the example above,
you can also use the following shorthand:
```md
[my-evaluation]{.tcrf reftype=pagenote}
```
You can refer to headers as well using either explicit or automatically generated identifiers (see Pandoc user’s guide).
In fact, you can use any identifier, including those automatically set by Pandoc.
To suppress the prefixes (e.g. “p. ”), you can set the `prefixref` attribute to `no` (defaults to `yes`). It can be useful, for instance, for small manually formatted indexes[^1]:
To suppress the prefixes (e.g. “p. ”), you can set the `prefixref` attribute to `no` (defaults to `yes`).
It can be useful, for instance, for small manually formatted indexes[^comma-syntax]:
``` markdown
Gaboriau: [publication, my-evaluation, reception]{.tcrf prefixref=no}
```
[^1]: About the comma-delimited syntax used in this example, see [the section on enumerations below](#enums).
[^comma-syntax]: About the comma-delimited syntax used in this example, see [the section on enumerations below](#enums).
### Page ranges
@ -111,15 +141,22 @@ You can refer to a page range like this:
If you want to know more about _L'Affaire Lerouge_, see [publication>reception]{.tcrf}.
```
The separator (here `>`) can be set to any string composed of characters other than alphanumeric, period, colon, underscore, hyphen and space.
The separator (here `>`) can be set to any string of characters
other than alphanumeric, period, colon, underscore, hyphen and space
(see the [customization options](#common-opts)).
In LaTeX and ConTeXt output, the above-mentionned `\tcrfenum` macro should be defined so that the range is printed as a simple page reference if the page numbers are identical. The syntax of a range is:
In LaTeX and ConTeXt output, the above-mentionned `\tcrfenum` macro
should be defined so that the range is printed as a simple page reference if the page numbers are identical.
The syntax of a range is[^customize-range-tex]:
``` tex
\tcrfenum{{publication to reception}}
```
In DOCX and ODT/Opendocument output, the same result can be achieved in a word processor by automatically searching and replacing duplicates with regular expressions and/or macros.
[^customize-range-tex]: Note that [it can be customized](#tex-options).
In DOCX and ODT/Opendocument output,
a range will be printed as a range even if the numbers are identical.
### Enumerations {#enums}
@ -129,8 +166,10 @@ You can enumerate several references as a comma-delimited list, for instance:
[ref-one, ref-two>ref-three, ref-four]{.tcrf}
```
In DOCX and ODT/Opendocument output, all these references will be printed, potentially resulting in unnecessary repetitions.
In TeX-based output formats, they will be wrapped in `\tcrfenum` like this:
In DOCX and ODT/Opendocument output, all these references will be printed,
potentially resulting in unnecessary repetitions.
In TeX-based output formats, they will be wrapped in `\tcrfenum` like this
and should be collapsed by the macro when it is desirable:
``` tex
\tcrfenum{{ref-one}{ref-two to ref-three}{ref-four}}
@ -138,18 +177,18 @@ In TeX-based output formats, they will be wrapped in `\tcrfenum` like this:
## Customization
### Common options
### Common options {#common-opts}
The following metadata fields can be set as strings:
* `tcrf-references-enum-separator`:
* the string between two references in an enumeration in a reference span; can be composed of any characters not authorized in an identifier;
* defaults to `, ` (with a space after the comma).
* the string between two references in an enumeration in a reference span;
* defaults to a comma followed by a space.
* `tcrf-references-range-separator`:
* the string used to separate two references in a reference span; can be composed of any characters not authorized in an identifier;
* the string used to separate two references in a reference span;
* defaults to `>`.
* `tcrf-only-explicit-labels`:
* set it to `true` if you want that _tcrf_ handle only spans with class `label`;
* set it to `true` if you want _tcrfenum_ to refer to spans with class `label` only;
* defaults to `false`.
* `tcrf-default-prefixref`:
* default value for the `prefixref` attribute;
@ -157,14 +196,11 @@ The following metadata fields can be set as strings:
* `tcrf-default-reftype`:
* default value for the `reftype` attribute;
* defaults to `page`.
* `tcrf-filelabel-ref-separator`:
* only useful in conjunction with the text-exrefs filter;
* separator between external files' labels and references;
* defaults to `::`.
### Options specific to DOCX and ODT/Opendocument
Here are some metadata fields only useful in conjunction with `docx`, `odt` and `opendocument` formats (see [above](#prefixes-tex) why they are ignored with `context` and `latex`):
Here are some metadata fields for the `docx`, `odt` and `opendocument` formats only
(see [above](#prefixes-tex) why they are ignored in ConTeXt and LaTeX output):
* `tcrf-page-prefix`:
* “page” prefix;
@ -179,33 +215,39 @@ Here are some metadata fields only useful in conjunction with `docx`, `odt` and
* “notes” prefix;
* defaults to `nn. `.
* `tcrf-pagenote-separator`:
* the separator between the references when `reftype` is set to `pagenote`;
* defaults to `, `.
* the separator between the enumerated references in the output file
when `reftype` is set to `pagenote`;
* defaults to a comma followed by a space.
* `tcrf-pagenote-at-end`:
* the string printed at the end of a pagenote reference;
* defaults to the empty string, can be used to achieve something like *n. 3 (p. 5)*.
* the string printed at the end of a `pagenote` reference in the output file;
* defaults to the empty string, but it can be used to achieve something like *n. 3 (p. 5)*
(see the sample file).
* `tcrf-pagenote-factorize-first-prefix-in-enum`:
* defines if the prefixes of the type printed first in a reference to page and note should be repeated (e.g. “p. 6, n. 1 and p. 9, n. 3”) or expressed globally at the beginning of the enumeration (e.g. “pp. 6, n. 1 and 9, n. 3”);
* defines if the prefixes of the type printed first in a reference to page and note
should be repeated (like in “p. 6, n. 1 and p. 9, n. 3”)
or set globally at the beginning of the enumeration (like in “pp. 6, n. 1 and 9, n. 3”);
* defaults to `no`, can be set to `yes`.
* `tcrf-pagenote-first-type`:
* the information that is printed first in references to page and note;
* the type of the reference number that is printed first in references to page and note;
* defaults to `page`, can be set to `note`.
* `tcrf-range-separator`:
* the string inserted between the page numbers in a range;
* the string separating the page numbers in a range;
* defaults to `–`.
* `tcrf-references-enum-separator`:
* the string used to separate the elements of an enumeration in a reference span;
* the string separating the elements of an enumeration in a reference span;
* defaults to a comma followed by a space.
* `tcrf-multiple-delimiter`:
* the string inserted between two elements (but the two last ones) in an enumeration;
* the string between two elements (but the two last ones) in an enumeration;
* defaults to a comma followed by a space.
* `tcrf-multiple-before-last`:
* the string inserted between the two last elements in an enumeration;
* defaults to `and` surrounded with spaces.
### Options specific to the formats based on TeX
### Options specific to the formats based on TeX {#tex-options}
Since TeX is extensible, you may wish to support types other than `page`, `note` and `pagenote` for ConTeXt and LaTeX output. `tcrf-additional-types` can be provided with a list of supplementary accepted types, e.g.:
Since TeX is extensible, you may wish to support types
other than `page`, `note` and `pagenote` for ConTeXt and LaTeX output.
`tcrf-additional-types` can be provided with a list of supplementary accepted types, e.g.:
``` yaml
tcrf-additional-types:
@ -213,19 +255,24 @@ tcrf-additional-types:
- figure
```
Once declared, these types can be used as the value of `reftype`
in the same way as `page`, `note` and `pagenote`.
In addition, the following metadata field can be used to control the rendering of ranges of labels in `\tcrfenum`:
* `tcrf-range-delim-tcrfenum`:
* the delimiter between the labels of a range in the list of references passed to `\tcrfenum`;
* defaults to ` to ` (mind the spaces).
* the delimiter between the labels of a range in the TeX output file;
* defaults to `to` surrounded with spaces.
## Compatibility with other filters
Text-crossrefs must be run after all other filters that can create, delete or move
footnotes, like citeproc.
_text-crossrefs_ must be run after all filters that may create, delete or move footnotes, such as citeproc.
In order to give and identifier to a note produced by a citation inside square brackets, the span should not include the citation key, the locator or the `;`
delimiter. If it is placed immediatly after the locator, this should be surrounded by curly brackets. So this should work:
In a citation inside square brackets, the span bearing an identifier should not include
a citation key, a locator or a `;` delimiter.
When it follows immediatly the locator,
you should protect the locator with curly brackets.
For example, this should work:
``` markdown
[@Jones1973, p. 5-70; @Doe2004[]{#jones-doe}]
@ -244,7 +291,3 @@ not that:
[@Jones1973, p. 5-70[]{#ref-to-jones}; @Doe2004]
```
You can set classes and attributes to your spans other than those defined by text-crossrefs (for instance `[some text]{#to-be-referred-to .highlighted color=red}` or `[reference]{.tcrf color=red}`). No span is removed.
Text-crossrefs is fully compatible with text-extrefs. Whenever possible, when a metadata is not set for text-extrefs, its value is taken from its text-crossrefs equivalent, so that you don't need to duplicate similar variables.