From 666c612a02f495d95eed0d30d2bc061b48bd13ef Mon Sep 17 00:00:00 2001 From: Bastien Dumont Date: Wed, 19 Oct 2022 20:35:31 +0200 Subject: [PATCH] Improvement of the documentation and update of the sample --- README.md | 155 ++++++++++++++++++++++++++++++++++++++++-------------- sample.md | 24 +++++---- 2 files changed, 129 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index c06f5ea..eb553f8 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,29 @@ currently supports the following target formats: * odt * opendocument -It doesn't permit to refer to references in other files: if you want to do this, use text-extrefs. +It does not permit to refer to references in other files: if you want to do this, use text-extrefs. -N.-B.: When opening for the first time a DOCX or ODT/Opendocument 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. +## 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. + +### 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: + + * \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) + +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: + + * [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 suffixed with `_note`. ## Usage @@ -34,97 +54,152 @@ identifier composed of alphanumeric characters, periods, colons, underscores and 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 `type` attribute (defaults to `page`). For instance, this: +the value of the `reftype` attribute (defaults to `page`). For instance, this: ``` markdown -See [publication]{.ref} for the publication date. I gave my -opinion in [my-evaluation]{.ref type=note}, [my-evaluation]{.ref}. +See [publication]{.tcrf} for the publication date. I gave my +opinion in [my-evaluation]{.tcrf reftype=note}, [my-evaluation]{.tcrf}. ``` -will render in LaTeX output: +will render in ConTeXt or LaTeX output: ``` tex -See p. \pageref{publication} for the publication date. I expressed -my thoughts about it in \ref{my-evaluation}, -p. \pageref{my-evaluation}. +See \tcrfenum{{publication}} for the publication date. I expressed +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: ```md -[my-evaluation]{.ref type=pagenote} +[my-evaluation]{.tcrf reftype=pagenote} ``` You can refer to headers as well using either explicit or automatically generated identifiers (see Pandoc user’s guide). +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]: + +``` 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). + ### Page ranges You can refer to a page range like this: ``` markdown -If you want to know more about _L'Affaire Lerouge_, see [publication>reception]{.ref}. +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. -In LaTeX and ConTeXt output, the page range will be printed as a simple page reference if the page numbers are identical. You can provide your own definition of the macro `\tcrfpagerangeref[]{}{}` in the preamble. In DOCX and ODT/Opendocument output, the same result can be achieved in a word processor by the means of automatic search and replace with regular expressions. +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: -## Enumerations +``` tex +\tcrfenum{{publication to reception}} +``` -Rather +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. -Enumerations are only supported for references to page and note numbers. +### Enumerations {#enums} + +You can enumerate several references as a comma-delimited list, for instance: + +``` markdown +[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: + +``` tex +\tcrfenum{{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; can be composed of any characters not authorized in an identifier; + * defaults to `, ` (with a space after the comma). + * `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; + * defaults to `>`. + * `tcrf-only-explicit-labels`: + * set it to `true` if you want that _tcrf_ handle only spans with class `label`; + * defaults to `false`. + * `tcrf-default-prefixref`: + * default value for the `prefixref` attribute; + * defaults to `yes`. + * `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`): + * `tcrf-page-prefix`: * “page” prefix; * defaults to `p. `. * `tcrf-pages-prefix`: * “pages” prefix; - * defaults to `p. `. + * defaults to `pp. `. * `tcrf-note-prefix`: * “note” prefix; * defaults to `n. `. * `tcrf-notes-prefix`: * “notes” prefix; - * defaults to `n. `. + * defaults to `nn. `. * `tcrf-pagenote-separator`: - * the separator between the references when `type` is set to `pagenote`; + * the separator between the references when `reftype` is set to `pagenote`; * defaults to `, `. * `tcrf-pagenote-at-end`: * the string printed at the end of a pagenote reference; - * defaults to an empty string, can be used to achieve something like *n. 3 (p. 5)*. - * `tcrf-pagenote-order`: - * the order in which the references to note and page are printed; - * defaults to `pagefirst`, can be set to `notefirst`. - * `tcrf-references-range-separator`: - * the string used to separate two references in a reference span; can be composed of any character not authorized in an identifier other than space or tab; - * defaults to `>`. + * defaults to the empty string, can be used to achieve something like *n. 3 (p. 5)*. + * `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”); + * defaults to `no`, can be set to `yes`. + * `tcrf-pagenote-first-type`: + * the information 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 to page numbers in a range; - * defaults to `-`. + * the string inserted between the page numbers in a range; + * defaults to `–`. * `tcrf-references-enum-separator`: - * the character used to separate the elements of an enumeration in a reference span; can be any character not authorized in an identifier other than space or tab; - * defaults to `;`. + * the string used to separate 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; * 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. - * `tcrf-only-explicit-labels`: - * set it to `true` if you want that _tcrf_ handle only spans with class `label`; - * defaults to `false`. - * `tcrf-default-info-type`: - * default value for the `type` attribute (`note`, `page` or `pagenote`); - * 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 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.: + +``` yaml +tcrf-additional-types: +- line +- figure +``` + +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). ## Compatibility with other filters @@ -152,6 +227,6 @@ 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]{.ref color=red}`). No span is removed. +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. diff --git a/sample.md b/sample.md index e78a2cf..781f7fb 100644 --- a/sample.md +++ b/sample.md @@ -3,6 +3,8 @@ tcrf-pagenote-separator: '\ (' tcrf-pagenote-at-end: ')' --- +(About the notes, see [toc-notes-begin>toc-notes-end]{.tcrf}.) + Émile Gaboriau published [_L'Affaire Lerouge_ in 1866]{#publication}.[^1] @@ -10,20 +12,22 @@ tcrf-pagenote-at-end: ')' [It was very popular.]{#reception} -See [publication]{.ref} for the publication date. I expressed -my thoughts about it in [my-evaluation]{.ref type=pagenote}. +See [publication]{.tcrf} for the publication date. I expressed +my thoughts about it in [my-evaluation]{.tcrf reftype=pagenote}. -If you want to know more about _L'Affaire Lerouge_, see [publication>reception]{.ref}. +If you want to know more about _L'Affaire Lerouge_, see [publication>reception]{.tcrf}. Here are some precisions.[^2] [^2]: [Whatever format]{#format} you choose, you can [refer to a note]{#refer-to-note} by the identifier of [any of its spans. You can even [nest spans]{#nested-spans}!]{#which-identifier} -I want to refer to a note: +[I want to refer to a note]{#toc-notes-begin}: - * How can I refer to a note by its number? → See [refer-to-note]{.ref}. - * What formats are supported? → See [format]{.ref}. - * What if the note contains multiple spans with identifiers? → See [which-identifier]{.ref}. - * What happens if a span in contained in a span? → See [nested-spans]{.ref}. - * What are the notes? → [my-evaluation;format;refer-to-note]{.ref type=note} - * Where are the notes? → [my-evaluation;format]{.ref} + * How can I refer to a note by its number? → See [refer-to-note]{.tcrf}. + * What formats are supported? → See [format]{.tcrf}. + * What if the note contains multiple spans with identifiers? → See [which-identifier]{.tcrf}. + * What happens if a span in contained in a span? → See [nested-spans]{.tcrf}. + * What are the notes? → [my-evaluation, format, refer-to-note]{.tcrf reftype=note} + * Where are the notes? → [my-evaluation, format]{.tcrf} + +[]{#toc-notes-end}