.. | ||
test | ||
LICENSE.txt | ||
Makefile | ||
README.md | ||
sample.md | ||
text-crossrefs.lua |
text-crossrefs: cross-references to arbitrary portions of text in Pandoc
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
- latex
- odt
- opendocument
Format-specific preliminary notices
DOCX and ODT/Opendocument
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.
ConTeXt specifically
Your template should include the following directive before \starttext
(as in the default template for ConTeXt):
$for(header-includes)$
$header-includes$
$endfor$
All TeX-based formats
All references are wrapped in a macro named \crossrefenum
.
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 \crossrefenum
is a group enclosing one or more groups.
Each of them contain a reference (either a single reference or a range).
Here are some valid invocations:
\crossrefenum[note][withprefix]{{lblone}{lbltwo}{lblthree}}
\crossrefenum[page][noprefix]{{lblone}{lbltwo}{lblthree}}
\crossrefenum[noprefix]{{lblone}{lbltwo}{lblthree}}
(the first argument defaults topage
)\crossrefenum{{lblone}{lbltwo}{lblthree}}
(the second argument defaults towithprefix
)\crossrefenum{{only-one}}
(even if the enumeration is limited to one item, it must be in a group)\crossrefenum{{lblone to lbltwo}{lblthree}}
(the first reference points to a range)
It is up to you to define \crossrefenum
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.
Alternatively, you can use my implementation,
which currently supports ConTeXt and LaTeX.
Here are some hints about the implementation of the \crossrefenum
macro:
-
[The
\crossrefenum
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 withnote:
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 theheader-includes
metadata variable like the default one does, this redefinition will happen automatically. Otherwise, you can copy-paste the following code in your preamble:\catcode`\@=11 \let\origfootnote\footnote \def\footnote#1#2{ \def\crfnm@secondArg{#2}% \ifx\crfnm@secondArg\crfnm@bracket \def\crfnm@todo{\crfnm@footnote@withlabel{#1}#2} % \else \def\crfnm@todo{\origfootnote{#1}#2}% \fi \crfnm@todo } \def\crfnm@bracket{[} \def\crfnm@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 or hyphens:
Émile Gaboriau published [_L'Affaire Lerouge_ in
1866]{#publication}.[^1]
[^1]: It is a very [fine piece of literature]{#my-evaluation}.
[It was very popular.]{#reception}
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:
See [publication]{.tcrf} for the publication date. I gave my
opinion in [my-evaluation]{.tcrf reftype=note}, [my-evaluation]{.tcrf}.
will render in ConTeXt or LaTeX output:
See \crossrefenum{{publication}} for the publication date. I expressed
my thoughts about it in \crossrefenum[note]{{my-evaluation}},
\crossrefenum{{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:
[my-evaluation]{.tcrf reftype=pagenote}
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 indexes1:
Gaboriau: [publication, my-evaluation, reception]{.tcrf prefixref=no}
Controlling where the label is placed
By default, labels are placed at the beginning of the spans.
You can change this via the attribute refanchor
, which can be set to:
beg
(default);end
;both
.
When the value is both
, text-crossrefs creates two labels
by suffixing -beg
and -end
to the identifier.
A typical use case is:
[A portion of text that may cross a page break.]{#mylbl refanchor=both}
See [mylbl-beg>mylbl-end]{.tcrf}.
Page ranges
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 of characters
other than alphanumeric, period, colon, underscore, hyphen and space
(see the customization options).
In LaTeX and ConTeXt output, the above-mentionned \crossrefenum
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 is2:
\crossrefenum{{publication to reception}}
In DOCX and ODT/Opendocument output, a range will be printed as a range even if the numbers are identical.
Enumerations
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 \crossrefenum
like this
and should be collapsed by the macro when it is desirable:
\crossrefenum{{ref-one}{ref-two to ref-three}{ref-four}}
Customization
Common options
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;
- defaults to a comma followed by a space.
tcrf-references-range-separator
:- the string used to separate two references in a reference span;
- defaults to
>
.
tcrf-only-explicit-labels
:- set it to
true
if you want crossrefenum to refer to spans with classlabel
only; - defaults to
false
.
- set it to
tcrf-default-prefixref
:- default value for the
prefixref
attribute; - defaults to
yes
.
- default value for the
tcrf-default-reftype
:- default value for the
reftype
attribute; - defaults to
page
.
- default value for the
Options specific to DOCX and ODT/Opendocument
Here are some metadata fields for the docx
, odt
and opendocument
formats only
(see above why they are ignored in ConTeXt and LaTeX output):
tcrf-page-prefix
:- “page” prefix;
- defaults to
p.
.
tcrf-pages-prefix
:- “pages” prefix;
- defaults to
pp.
.
tcrf-note-prefix
:- “note” prefix;
- defaults to
n.
.
tcrf-notes-prefix
:- “notes” prefix;
- defaults to
nn.
.
tcrf-pagenote-separator
:- the separator between the enumerated references in the output file
when
reftype
is set topagenote
; - defaults to a comma followed by a space.
- the separator between the enumerated references in the output file
when
tcrf-pagenote-at-end
:- 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).
- the string printed at the end of a
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 (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 toyes
.
tcrf-pagenote-first-type
:- the type of the reference number that is printed first in references to page and note;
- defaults to
page
, can be set tonote
.
tcrf-range-separator
:- the string separating the page numbers in a range;
- defaults to
–
.
tcrf-references-enum-separator
:- 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 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
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.:
tcrf-additional-types:
- line
- 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 \crossrefenum
:
tcrf-range-delim-crossrefenum
:- 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 filters that may create, delete or move footnotes, such as citeproc.
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:
[@Jones1973, p. 5-70; @Doe2004[]{#jones-doe}]
[@Jones1973, p. 5-70; [it was elaborated upon]{#further-elaboration} by @Doe2004]
[@Jones1973, {p. 5-70}[]{#ref-to-jones}; @Doe2004]
not that:
[[@Jones1973, p. 5-70]{#ref-to-jones}; @Doe2004]
[[@Jones1973, p. 5-70; @Doe2004]{#jones-doe}]
[@Jones1973, p. 5-70[]{#ref-to-jones}; @Doe2004]
-
About the comma-delimited syntax used in this example, see the section on enumerations below. ↩︎
-
Note that it can be customized. ↩︎