From ac7abe5ef0fc89a202a1e412089796a7f154faa6 Mon Sep 17 00:00:00 2001 From: Bastien Dumont Date: Sat, 5 Nov 2022 21:05:49 +0100 Subject: [PATCH] Clean up and reformat the README, removing references to text-extrefs --- README.md | 203 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 123 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index c406a8b..63a83a9 100644 --- a/README.md +++ b/README.md @@ -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.