pandoc-crossref man page

gistfile1.txt

.\" Automatically generated by Pandoc 1.19.2.1
.\"
.TH "PANDOC\-CROSSREF" "1" "Octobre 2017" "" ""
.hy
.SH pandoc\-crossref
.PP
pandoc\-crossref is a pandoc filter for numbering figures, equations,
tables and cross\-references to them.
.PP
Input file (like
demo.md (https://raw.githubusercontent.com/lierdakil/pandoc-crossref/gh-pages/demo.md))
can be converted into
html (http://lierdakil.github.io/pandoc-crossref/output.html),
latex (http://lierdakil.github.io/pandoc-crossref/output.latex),
pdf (http://lierdakil.github.io/pandoc-crossref/output.pdf),
md (http://lierdakil.github.io/pandoc-crossref/output.md) or other
formats.
.PP
Optionally, you can use cleveref for latex/pdf output, e.g.
cleveref
pdf (http://lierdakil.github.io/pandoc-crossref/output-cref.pdf),
cleveref
latex (http://lierdakil.github.io/pandoc-crossref/output-cref.latex),
and listings package, e.g.
listings
pdf (http://lierdakil.github.io/pandoc-crossref/output-listings.pdf),
listings
latex (http://lierdakil.github.io/pandoc-crossref/output-listings.latex)
.PP
You can also enable per\-chapter numbering (as with
\f[C]\-\-chapters\f[] for latex output).
You need to specify \f[C]\-M\ chapters\f[] for non\-latex/pdf output
however.
Examples:
html (http://lierdakil.github.io/pandoc-crossref/output-chapters.html),
markdown (http://lierdakil.github.io/pandoc-crossref/output-chapters.md),
latex (http://lierdakil.github.io/pandoc-crossref/output-chapters.latex),
pdf (http://lierdakil.github.io/pandoc-crossref/output-chapters.pdf).
.PP
This work is inspired by
pandoc\-fignos (https://github.com/tomduck/pandoc-fignos) and
pandoc\-eqnos (https://github.com/tomduck/pandoc-eqnos) by \@tomduck.
.PP
This package tries to use latex labels and references if output type is
LaTeX.
It also tries to supplement rudimentary LaTeX configuration that should
mimic metadata configuration by setting \f[C]header\-includes\f[]
variable.
.SH Caveats
.SS LaTeX output and \f[C]\-\-include\-in\-header\f[]
.PP
pandoc\-crossref uses metadata variable \f[C]header\-includes\f[] to add
LaTeX definitions to output.
However, Pandoc\[aq]s command line option
\f[C]\-\-include\-in\-header\f[]/\f[C]\-H\f[] overrides this variable.
If you need to use \f[C]\-\-include\-in\-header\f[], add
pandoc\-crossref\-specific definitions as well.
See LaTeX customization (#latex-customization) for more information.
.SS pandoc\-citeproc and pandoc\-crossref
.PP
Since pandoc\-crossref uses the same citation syntax as
pandoc\-citeproc, you \f[I]have\f[] to run former \f[I]before\f[]
latter.
For example:
.IP
.nf
\f[C]
pandoc\ \-F\ pandoc\-crossref\ \-F\ pandoc\-citeproc\ file.md\ \-o\ file.html
\f[]
.fi
.SS Note on leading/trailing spaces in metadata options
.PP
Leading and trailing spaces in YAML metadata will most likely be
stripped by either YAML parser or Pandoc itself.
If you need leading and/or trailing spaces in pandoc\-crossref metadata
variables, use html entity for space instead, i.e.
\f[C] \f[].
For example, if you want reference ranges to be delimited by a dash with
spaces (e.g.
\f[C]2\ \-\ 5\f[]), include the following in YAML metadata:
.IP
.nf
\f[C]
rangeDelim:\ \[aq] \- \[aq]
\f[]
.fi
.PP
or pass \f[C]\-MrangeDelim=\[aq] \- \[aq]\f[] to pandoc on
command line.
.PP
You can use other html entites of course, like \f[C] \f[] etc.
.SH Syntax
.PP
Syntax is loosely based on discussion in
<https://github.com/jgm/pandoc/issues/813>
.SS Image labels
.IP
.nf
\f[C]
![Caption](file.ext){#fig:label}
\f[]
.fi
.PP
To label an (implicit) figure, append \f[C]{#fig:label}\f[] (with
\f[C]label\f[] being something unique to reference this figure by)
immediately after image definition.
.PP
This only works on implicit figures, i.e.
an image occurring by itself in a paragraph (which will be rendered as a
figure with caption by pandoc)
.PP
Image block and label \f[I]can not\f[] be separated by spaces.
.SS Subfigures
.PP
It\[aq]s possible to group figures as subfigures.
Basic syntax is as follows:
.IP
.nf
\f[C]
<div\ id="fig:figureRef">
![subfigure\ 1\ caption](image1.png){#fig:figureRefA}

![subfigure\ 2\ caption](image2.png){#fig:figureRefB}

Caption\ of\ figure
</div>
\f[]
.fi
.PP
To sum up, subfigures are made with a div having a figure \f[C]id\f[].
Contents of said div consist of several paragraphs.
All but last paragraphs contain one subfigure each, with captions,
images and (optionally) reference attributes.
Last paragraph contains figure caption.
.PP
If you put more than one figure in the paragraph, those will still be
rendered, but Pandoc will omit subfigure caption in most outputs (but it
will work as expected with LaTeX).
You can use output\-specific hacks to work around that, or use
\f[C]subfigGrid\f[] (see below).
.PP
Output is customizable, with metadata fields.
See Customization (#customization) for more information.
.PP
Default settings will produce the following equivalent Markdown from
example above:
.IP
.nf
\f[C]
<div\ id="fig:figureRef"\ class="subfigures">

![a](image1.png){#fig:figureRefA}

![b](image2.png){#fig:figureRefB}

Figure\ 1:\ Caption\ of\ figure.\ a\ \[em]\ subfigure\ 1\ caption,\ b\ \[em]\ subfigure\ 2
caption

</div>
\f[]
.fi
.PP
References to subfigures will be rendered as
\f[C]figureNumber\ (subfigureNumber)\f[], e.g., in this particular
example, \f[C][\@fig:figureRefA]\f[] will produce \f[C]fig.\ 1\ (a)\f[].
.PP
You can add \f[C]nocaption\f[] class to an image to suppress subfigure
caption altogether.
Note that it will still be counted.
.SS Subfigure grid
.PP
If you need to align subfigures in a grid, and using output format
styles is not an option, you can use \f[C]subfigGrid\f[] option.
That will typeset subfigures inside a table.
.PP
Rows are formed by different paragraphs, with each image in a separate
column.
.PP
Column widths will be taken from \f[C]width\f[] attributes of
corresponding images, e.g.
.IP
.nf
\f[C]
<div\ id="fig:coolFig">
![caption\ a](coolfiga.png){#fig:cfa\ width=30%}
![caption\ b](coolfigb.png){#fig:cfb\ width=60%}
![caption\ c](coolfigb.png){#fig:cfc\ width=10%}

![caption\ d](coolfigd.png){#fig:cfd}
![caption\ e](coolfige.png){#fig:cfe}
![caption\ f](coolfigf.png){#fig:cff}

Cool\ figure!
</div>
\f[]
.fi
.PP
will produce a table with columns of 30%, 60% and 10% respectively.
.PP
Only first row of images is considered for table width computation,
other rows are completely ignored.
.PP
\f[I]Anything\f[] except images is silently ignored.
So any text, spaces, soft line breaks etc will silently disappear from
output.
That doesn\[aq]t apply to caption paragraph, obviously.
.PP
All images will have width attribute automatically set to \f[C]100%\f[]
in order to fill whole column.
.PP
Specifying width in anything but \f[C]%\f[] will throw an error.
.PP
If width for some images in first row is not specified, those will span
equally in the remaining space.
.PP
If width isn\[aq]t specified for any image in first row, those will span
equally on 99% of page width (due to Pandoc otherwise omitting width
attribute for table).
.PP
This option is ignored with LaTeX output, but paragraph breaks should
produce similar effect, so images should be typeset correctly.
TL;DR you don\[aq]t need \f[C]subfigGrid\f[] enabled for it to work with
LaTeX, but you can still enable it.
.SS Equation labels
.IP
.nf
\f[C]
$$\ math\ $$\ {#eq:label}
\f[]
.fi
.PP
To label a display equation, append \f[C]{#eq:label}\f[] (with
\f[C]label\f[] being something unique to reference this equation by)
immediately after math block.
.PP
Math block and label \f[I]can\f[] be separated by one or more spaces.
.PP
You can also number all display equations with \f[C]autoEqnLabels\f[]
metadata setting (see below).
Note, however, that you won\[aq]t be able to reference equations without
explicit labels.
.PP
Equations numbers will be typeset inside math with \f[C]\\qquad\f[]
before them.
If you want to use tables instead, use \f[C]tableEqns\f[] option.
Depending on output format, tables might work better or worse than
\f[C]\\qquad\f[].
.SS Table labels
.IP
.nf
\f[C]
a\ \ \ b\ \ \ c
\-\-\-\ \-\-\-\ \-\-\-
1\ \ \ 2\ \ \ 3
4\ \ \ 5\ \ \ 6

:\ Caption\ {#tbl:label}
\f[]
.fi
.PP
To label a table, append \f[C]{#tbl:label}\f[] at the end of table
caption (with \f[C]label\f[] being something unique to reference this
table by).
Caption and label \f[I]must\f[] be separated by at least one space.
.SS Section labels
.PP
You can also reference sections of any level.
Section labels use native pandoc syntax, but must start with "sec:",
e.g.
.IP
.nf
\f[C]
#\ Section\ {#sec:section}
\f[]
.fi
.PP
You can also use \f[C]autoSectionLabels\f[] variable to automatically
prepend all section labels (automatically generated with pandoc
included) with "sec:".
Bear in mind that references can\[aq]t contain periods, commas etc, so
some auto\-generated labels will still be unusable.
.PP
WARNING: With LaTeX output, you have to invoke pandoc with
\f[C]\-\-number\-sections\f[], otherwise section labels won\[aq]t work.
It\[aq]s also advised with other output formats, since with no numbers
in section titles, it would be hard to navigate anyway.
.SS Section numbering
.PP
Pandoc doesn\[aq]t properly support numbering sections in some output
formats, and section reference labels (see below).
.PP
You can let pandoc\-crossref handle section numbering instedad.
This is done via \f[C]numberSections\f[] and \f[C]sectionsDepth\f[]
metadata options.
.PP
\f[C]numberSections\f[] controls if pandoc\-crossref handles numbering
sections, while \f[C]sectionsDepth\f[] controls what sections are
numbered.
.PP
Set \f[C]sectionsDepth\f[] to \f[C]0\f[] to make section numbering
consistent with \f[C]chaptersDepth\f[].
.PP
If \f[C]sectionsDepth\f[] value is lesser than \f[C]0\f[], all sections
will be numbered.
.PP
Otherwise, only header levels up to and including \f[C]sectionsDepth\f[]
will be numbered.
.SS Section reference labels
.PP
\f[B]\f[I]Not currently supported with LaTeX output\f[]\f[]
.PP
If you want to reference some section by a pre\-defined label instead of
by number, you can specify section attribute \f[C]label\f[], like this:
.IP
.nf
\f[C]
#\ Section\ {label="Custom\ Label"}
\f[]
.fi
.PP
This label will be used instead of section number in \f[C]chapters\f[]
output and when referencing section directly (with
\f[C]\@sec:section\f[]).
.PP
Note that with \f[C]chapters\f[] output with depth>1, only given section
will be referenced by custom label, e.g.
with
.IP
.nf
\f[C]
#\ Chapter\ 1.

#\ Section\ with\ custom\ label\ {#sec:scl\ label="SCL"}

![](figure.png){#fig:figure}
\f[]
.fi
.PP
\f[C]\@sec:scl\f[] will translate into \f[C]sec.\ 1.SCL\f[], and
\f[C]\@fig:figure\f[] into \f[C]fig.\ 1.SCL.1\f[]
.SS Code Block labels
.PP
There are a couple options to add code block labels.
Those work only if code block id starts with \f[C]lst:\f[], e.g.
\f[C]{#lst:label}\f[]
.SS \f[C]caption\f[] attribute
.PP
\f[C]caption\f[] attribute will be treated as code block caption.
If code block has both id and \f[C]caption\f[] attributes, it will be
treated as numbered code block.
.SS Table\-style captions
.PP
Enabled with \f[C]codeBlockCaptions\f[] metadata option.
If code block is immediately adjacent to paragraph, starting with
\f[C]Listing:\f[] or \f[C]:\f[], said paragraph will be treated as code
block caption.
.PP
or
.PP
It also allows to specify label in caption, as do tables, for example:
.SS Wrapping div
.PP
Wrapping code block without label in a div with id \f[C]lst:...\f[] and
class, starting with \f[C]listing\f[], and adding paragraph before code
block, but inside div, will treat said paragraph as code block caption.
.SS References
.IP
.nf
\f[C]
[\@fig:label1;\@fig:label2;...]\ or\ [\@eq:label1;\@eq:label2;...]\ or\ [\@tbl:label1;\@tbl:label2;...]\ or\ \@fig:label\ or\ \@eq:label\ or\ \@tbl:label
\f[]
.fi
.PP
Reference syntax heavily relies on citation syntax.
Basic reference is created by writing \f[C]\@\f[], then basically
desired label with prefix.
It is also possible to reference a group of objects, by putting them
into brackets with \f[C];\f[] as separator.
Similar objects will be grouped in order of them appearing in citation
brackets, and sequential reference numbers will be shortened, e.g.
\f[C]1,2,3\f[] will be shortened to \f[C]1\-3\f[].
.PP
You can capitalize first reference character to get capitalized prefix,
e.g.
\f[C][\@Fig:label1]\f[] will produce \f[C]Fig.\ ...\f[] by default.
Capitalized prefixes are derived automatically by capitalizing first
letter of every word in non\-capitalized prefix, unless overridden with
metadata settings.
See Customization (#customization) for more information.
.SS Linking references
.PP
To make references into hyperlinks to referenced element, enable
\f[C]linkReferences\f[] metadata option.
This has no effect on LaTeX output, since in this case, hyperlinking
references is handled with \f[C]hyperref\f[] LaTeX package.
.SS Custom prefix per\-reference
.PP
It\[aq]s possible to provide your own prefix per\-reference, f.ex.
\f[C][Prefix\ \@reference]\f[] will replace default prefix
(\f[C]fig.\f[]/\f[C]sec.\f[]/etc) with prefix verbatim, e.g.
\f[C][Prefix\ \@fig:1]\f[] will be rendered as \f[C]Prefix\ 1\f[]
instead of \f[C]fig.\ 1\f[].
.PP
In citation group, citations with the same prefix will be grouped.
So, for example \f[C][A\ \@fig:1;\ A\ \@fig:2;\ B\ \@fig:3]\f[] will
turn into \f[C]A\ 1,\ 2,\ B\ 3\f[].
It can be used to an advantage, although it\[aq]s a bit more cumbersome
than it should be, e.g.
\f[C][Appendices\ \@sec:A1;\ Appendices\ \@sec:A2;\ Appendices\ \@sec:A3]\f[]
will turn into \f[C]Appendices\ \@A1\-\@A3\f[] (with \f[C]\@A1\f[] and
\f[C]\@A3\f[] being relevant section numbers).
Note that non\-contiguous sequences of identical prefixes \f[I]will
not\f[] be grouped.
.PP
\f[B]\f[I]Not supported with cleveref LaTeX output.\f[]\f[]
.SS Prefix suppression
.PP
Prepending \f[C]\-\f[] before \f[C]\@\f[], like so
\f[C][\-\@citation]\f[], will suppress default prefix, e.g.
\f[C][\-\@fig:1]\f[] will produce just \f[C]1\f[] (or whatever number it
happens to be) without \f[C]fig.\f[] prefix.
.PP
In citation group, citations with and without prefixes will be in
different groups.
So \f[C][\-\@fig:1;\ \@fig:2;\ \-\@fig:3]\f[] will be rendered as
\f[C]1,\ fig.\ 2,\ 3\f[], so be careful with this feature.
Again, non\-contiguous sequences are not grouped together.
.SS Lists
.PP
It\[aq]s possible to use raw latex commands \f[C]\\listoffigures\f[],
\f[C]\\listoftables\f[] and \f[C]listoflistings\f[], which will produce
ordered list of figure/table/listings titles, in order of appearance in
document.
.PP
\f[C]\\listoflistings\f[] depends on other options, and is defined in
preamble, so it will work reliably only with standalone/pdf output.
.SH Installation
.PP
Assuming you already installed Haskell
platform (http://hackage.haskell.org/platform/), you can install
pandoc\-crossref with cabal:
.IP
.nf
\f[C]
cabal\ update
cabal\ install\ pandoc\-crossref
\f[]
.fi
.PP
However, I highly recommend you use a sandbox for installation, e.g.
.IP
.nf
\f[C]
cabal\ update
mkdir\ pandoc\-crossref
cd\ pandoc\-crossref
cabal\ sandbox\ init
cabal\ install\ pandoc\-crossref
\f[]
.fi
.PP
This will get \f[C]pandoc\-crossref\f[] installed into
\f[C]\&.cabal\-sandbox/bin\f[].
Pandoc will also be built, if it\[aq]s not installed as a Haskell
library system\-wide.
You might also want to install \f[C]pandoc\-citeproc\f[] in the same
sandbox, if that\[aq]s the case
(\f[C]cabal\ install\ pandoc\-citeproc\f[]).
.PP
There are a few pre\-built executables available at releases
page (https://github.com/lierdakil/pandoc-crossref/releases/latest) for
Windows, OSX and Linux.
Bear in mind that those are a product of an automated build script, and
as such, provided as\-is, with zero guarantees.
.SS Notice Fedora users
.PP
\f[C]cabal\-install\f[] package is not enough to build pandoc\-crossref
(see #132).
To get sane Haskell build environment, you need to install
\f[C]haskell\-platform\f[] package
(\f[C]yum\ install\ haskell\-platform\f[]).
.PP
While on topic, if you don\[aq]t want to rebuild Pandoc itself from
source, make sure you have \f[C]pandoc\f[] and
\f[C]ghc\-pandoc\-devel\f[] yum packages before attempting to build
pandoc\-crossref.
.SH Usage
.PP
Run pandoc with \f[C]\-\-filter\f[] option, passing path to
pandoc\-crossref executable, or simply \f[C]pandoc\-crossref\f[], if
it\[aq]s in PATH:
.PP
\f[C]pandoc\ \-\-filter\ pandoc\-crossref\f[]
.PP
If you installed with cabal, it\[aq]s most likely located in
\f[C]$HOME/.cabal/bin\f[] on *NIX systems,
\f[C]$HOME/Library/Haskell/bin\f[] on Macs, or in
\f[C]%AppData%\\cabal\\bin\f[] on Windows.
.SS Customization
.PP
There are several parameters that can be set via YAML metadata (either
by passing \f[C]\-M\f[] to \f[C]pandoc\f[], or by setting it in source
markdown)
.PP
A list of variables follows.
.SS General options
.IP \[bu] 2
\f[C]cref\f[]: if True, latex export will use \f[C]\\cref\f[] from
cleveref package.
Only relevant for LaTeX output.
\f[C]\\usepackage{cleveref}\f[] will be automatically added to
\f[C]header\-includes\f[].
.IP \[bu] 2
\f[C]chapters\f[]: if True, number elements as \f[C]chapter.item\f[],
and restart \f[C]item\f[] on each first\-level heading (as
\f[C]\-\-chapters\f[] for latex/pdf output)
.IP \[bu] 2
\f[C]chaptersDepth\f[], default \f[C]1\f[]: header level to treat as
"chapter".
If \f[C]chaptersDepth>1\f[], then items will be prefixed with several
numbers, corresponding to header numbers, e.g.
\f[C]fig.\ 1.4.3\f[].
.IP \[bu] 2
\f[C]numberSections\f[], default \f[C]false\f[]: if True,
pandoc\-crossref will prepend section number to section titles (as
counted by pandoc\-crossref itself).
.IP \[bu] 2
\f[C]sectionsDepth\f[], default \f[C]0\f[]:
.RS 2
.IP \[bu] 2
sectionsDepth < 0 \-\- number all sections
.IP \[bu] 2
sectionsDepth == 0 \-\- be consistent with \f[C]chaptersDepths\f[]
.IP \[bu] 2
sectionsDepth > 0 \-\- number section levels up to and including
\f[C]sectionsDepth\f[]
.RE
.IP \[bu] 2
\f[C]listings\f[]: if True, generate code blocks for \f[C]listings\f[]
package.
Only relevant for LaTeX output.
\f[C]\\usepackage{listings}\f[] will be automatically added to
\f[C]header\-includes\f[].
You need to specify \f[C]\-\-listings\f[] option as well.
.IP \[bu] 2
\f[C]codeBlockCaptions\f[]: if True, parse table\-style code block
captions.
.IP \[bu] 2
\f[C]autoSectionLabels\f[], default \f[C]false\f[]: Automatically prefix
all section labels with \f[C]sec:\f[].
Note that this messes with pandoc\[aq]s automatic header references.
.IP \[bu] 2
\f[C]autoEqnLabels\f[], default \f[C]false\f[]: Automatically number all
display equations (i.e.
ones defined using \f[C]$$...$$\f[]/\f[C]\\[...\\]\f[]).
Note that you won\[aq]t be able to reference equations without explicit
labels.
.IP \[bu] 2
\f[C]tableEqns\f[], default \f[C]false\f[]: Typeset equations and
equation numbers in tables instead of embedding numbers into equations
themselves.
Depending on output format, this might work better or worse.
.SS Item title format
.IP \[bu] 2
\f[C]figureTitle\f[], default \f[C]Figure\f[]: Word(s) to prepend to
figure titles, e.g.
\f[C]Figure\ 1:\ Description\f[]
.IP \[bu] 2
\f[C]tableTitle\f[], default \f[C]Table\f[]: Word(s) to prepend to table
titles, e.g.
\f[C]Table\ 1:\ Description\f[]
.IP \[bu] 2
\f[C]listingTitle\f[], default \f[C]Listing\f[]: Word(s) to prepend to
listing titles, e.g.
\f[C]Listing\ 1:\ Description\f[]
.IP \[bu] 2
\f[C]titleDelim\f[], default \f[C]:\f[]: What to put between object
number and caption text.
.SS Subfigure\-specific
.PP
See Subfigures (#subfigures)
.IP \[bu] 2
\f[C]ccsDelim\f[], default \f[C],&nbsp;\f[]: delimiter for collected
subfigure captions.
See Subfigures (#subfigures) and Templates (#templates)
.IP \[bu] 2
\f[C]ccsLabelSep\f[], default \f[C]&nbsp;\[em]&nbsp;\f[]: delimiter used
between subfigure label and subfigure caption in collected captions.
See Subfigures (#subfigures) and Templates (#templates)
.IP \[bu] 2
\f[C]subfigGrid\f[], default \f[C]false\f[].
If true, typeset subfigures inside a table.
Ignored with LaTeX output.
See Subfigures (#subfigures)
.SS List titles
.IP \[bu] 2
\f[C]lofTitle\f[], default \f[C]#\ List\ of\ Figures\f[]: Title for list
of figures (lof)
.IP \[bu] 2
\f[C]lotTitle\f[], default \f[C]#\ List\ of\ Tables\f[]: Title for list
of tables (lot)
.IP \[bu] 2
\f[C]lolTitle\f[], default \f[C]#\ List\ of\ Listings\f[]: Title for
list of listings (lol)
.SS Reference format
.IP \[bu] 2
\f[C]figPrefix\f[], default \f[C]fig.\f[], \f[C]figs.\f[]: Prefix for
references to figures, e.g.
\f[C]figs.\ 1\-3\f[]
.IP \[bu] 2
\f[C]eqnPrefix\f[], default \f[C]eq.\f[], \f[C]eqns.\f[]: Prefix for
references to equations, e.g.
\f[C]eqns.\ 3,4\f[]
.IP \[bu] 2
\f[C]tblPrefix\f[], default \f[C]tbl.\f[], \f[C]tbls.\f[]: Prefix for
references to tables, e.g.
\f[C]tbl.\ 2\f[]
.IP \[bu] 2
\f[C]lstPrefix\f[], default \f[C]lst.\f[], \f[C]lsts.\f[]: Prefix for
references to lists, e.g.
\f[C]lsts.\ 2,5\f[]
.IP \[bu] 2
\f[C]secPrefix\f[], default \f[C]sec.\f[], \f[C]secs.\f[]: Prefix for
references to sections, e.g.
\f[C]secs.\ 2,5\f[]
.IP \[bu] 2
\f[C]chapDelim\f[], default \f[C]\&.\f[]: Delimiter between chapter
number and item number.
.IP \[bu] 2
\f[C]rangeDelim\f[], default \f[C]\-\f[]: Delimiter between reference
ranges, e.g.
\f[C]eq.\ 2\-5\f[]
.IP \[bu] 2
\f[C]pairDelim\f[], default \f[C],\f[]: Delimiter between pair of
reference ranges, e.g.
\f[C]eq.\ 2\-5\ <and>\ 7\-9\f[], or \f[C]eq.\ 2\ <and>\ 7\f[], but
\f[C]eq.\ 2,\ 4,\ 6\f[]
.IP \[bu] 2
\f[C]lastDelim\f[], default \f[C],\f[]: Delimiter between
second\-to\-last and last reference ranges, e.g.
\f[C]eq.\ 2\-5,\ 6\-8\ <and>\ 10\f[].
\f[C]pairDelim\f[] overrides this for cases of exactly two
references/ranges.
.IP \[bu] 2
\f[C]refDelim\f[], default \f[C],\f[]: Delimiter between references,
e.g.
\f[C]eq.\ 2,\ 5,\ 7\f[] or \f[C]eq.\ 2\-4,\ 6\-8\f[]
.IP \[bu] 2
\f[C]linkReferences\f[], default \f[C]false\f[]: Make references
hyperlinks to the referenced element
.PP
Note that none of the \f[C]*Delim\f[] options are honored with cleveref
output.
Use cleveref\[aq]s customization options instead.
.PP
\f[C]figPrefix\f[], \f[C]eqnPrefix\f[], \f[C]tblPrefix\f[],
\f[C]lstPrefix\f[] can be YAML arrays.
That way, value at index corresponds to total number of references in
group, f.ex.
.IP
.nf
\f[C]
figPrefix:
\ \ \-\ "fig."
\ \ \-\ "figs."
\f[]
.fi
.PP
Will result in all single\-value references prefixed with "fig.", and
all reference groups of two and more will be prefixed with "figs.":
.IP
.nf
\f[C]
[\@fig:one]\ \->\ fig.\ 1
[\@fig:one;\ \@fig:two]\ \->\ figs.\ 1,\ 2
[\@fig:one;\ \@fig:two;\ \@fig:three]\ \->\ figs.\ 1\-3
\f[]
.fi
.PP
They can be YAML strings as well.
In that case, prefix would be the same regardless of number of
references.
.PP
They can also be used with first character capitalized, i.e.
\f[C]FigPrefix\f[], etc.
In this case, these settings will override default reference
capitailzation settings.
.SS Custom numbering
.PP
See Custom Numbering Schemes (#custom-numbering-schemes)
.IP \[bu] 2
\f[C]figLabels\f[], default unset: custom numbering scheme for figures.
.IP \[bu] 2
\f[C]subfigLabels\f[], default \f[C]alpha\ a\f[]: custom numbering
scheme for subfigures.
.IP \[bu] 2
\f[C]eqnLabels\f[], default unset: custom numbering scheme for
equations.
.IP \[bu] 2
\f[C]tblLabels\f[], default unset: custom numbering scheme for tables.
.IP \[bu] 2
\f[C]lstLabels\f[], default unset: custom numbering scheme for listings.
.IP \[bu] 2
\f[C]secLabels\f[], default unset: custom numbering scheme for sections.
.SS Item title templates
.PP
See Templates (#templates)
.IP \[bu] 2
\f[C]figureTemplate\f[], default
\f[C]\\\\[figureTitle\\\\]\ \\\\[i\\\\]\\\\[titleDelim\\\\]\ \\\\[t\\\\]\f[]:
template for figure captions
.IP \[bu] 2
\f[C]tableTemplate\f[], default
\f[C]\\\\[tableTitle\\\\]\ \\\\[i\\\\]\\\\[titleDelim\\\\]\ \\\\[t\\\\]\f[]:
template for table captions
.IP \[bu] 2
\f[C]listingTemplate\f[], default
\f[C]\\\\[listingTitle\\\\]\ \\\\[i\\\\]\\\\[titleDelim\\\\]\ \\\\[t\\\\]\f[]:
template for listing captions
.SS Subfigure templates
.PP
See Subfigures (#subfigures)
.IP \[bu] 2
\f[C]subfigureTemplate\f[], default
\f[C]\\\\[figureTitle\\\\]\ \\\\[i\\\\]\\\\[titleDelim\\\\]\ \\\\[t\\\\].\ \\\\[ccs\\\\]\f[]:
template for subfigure divs captions.
.IP \[bu] 2
\f[C]subfigureChildTemplate\f[], default \f[C]\\\\[i\\\\]\f[]: template
for actual subfigure captions.
.IP \[bu] 2
\f[C]ccsTemplate\f[], default
\f[C]\\\\[i\\\\]\\\\[ccsLabelSep\\\\]\\\\[t\\\\]\f[]: template for
collected subfigure captions.
.SS Reference templates
.PP
See Templates (#templates)
.IP \[bu] 2
\f[C]figPrefixTemplate\f[], default
\f[C]\\\\[p\\\\]&nbsp;\\\\[i\\\\]\f[] \-\- figure reference template
.IP \[bu] 2
\f[C]eqnPrefixTemplate\f[], default
\f[C]\\\\[p\\\\]&nbsp;\\\\[i\\\\]\f[] \-\- equation reference template
.IP \[bu] 2
\f[C]tblPrefixTemplate\f[], default
\f[C]\\\\[p\\\\]&nbsp;\\\\[i\\\\]\f[] \-\- table reference template
.IP \[bu] 2
\f[C]lstPrefixTemplate\f[], default
\f[C]\\\\[p\\\\]&nbsp;\\\\[i\\\\]\f[] \-\- listing reference template
.IP \[bu] 2
\f[C]secPrefixTemplate\f[], default
\f[C]\\\\[p\\\\]&nbsp;\\\\[i\\\\]\f[] \-\- section reference template
.IP \[bu] 2
\f[C]refIndexTemplate\f[], default \f[C]\\\\[i\\\\]\\\\[suf\\\\]\f[]
\-\- individual reference index template
.IP \[bu] 2
\f[C]subfigureRefIndexTemplate\f[], default
\f[C]\\\\[i\\\\]\\\\[suf\\\\]\ (\\\\[s\\\\])\f[] \-\- subfigure
reference index template
.SS LaTeX customization
.PP
Support for above variables with LaTeX/PDF output is limited.
In particular, the following variables are honored:
.IP \[bu] 2
\f[C]figureTitle\f[]
.IP \[bu] 2
\f[C]tableTitle\f[]
.IP \[bu] 2
\f[C]listingTitle\f[]
.IP \[bu] 2
\f[C]lofTitle\f[] \-\- ignores formatting
.IP \[bu] 2
\f[C]lotTitle\f[] \-\- ignores formatting
.IP \[bu] 2
\f[C]lolTitle\f[] \-\- ignores formatting
.IP \[bu] 2
\f[C]*Prefix\f[], upper\-/lowercase and single/plural form.
Note that with cleveref output, if \f[C]*Prefix\f[] is array, only first
two items are used, and the rest is ignored.
.PP
Templates are \f[I]not\f[] supported.
.PP
You can add arbitrary LaTeX commands to document header, however, using
\f[C]header\-includes\f[] metadata field.
Please bear in mind, that pandoc\-crossref up to and including 0.1.2.1
requires \f[C]header\-includes\f[] to be YAML array, e.g.
.IP
.nf
\f[C]
header\-includes:
\ \ \ \ \-\ "\\\\newcommand{\\\\pcdoc}{Pandoc\-crossref\ documentation}"
\f[]
.fi
.PP
This will be added \f[I]before\f[] any customization applied by
pandoc\-crossref.
For a complete list of what is added to template, consult
ModifyMeta.hs (https://github.com/lierdakil/pandoc-crossref/blob/master/src/Util/ModifyMeta.hs).
.SS Templates
.PP
pandoc\-crossref supports advanced caption customization via caption
templates.
Templates are specified as YAML metadata variables (see
Customization (#customization)), and are parsed as default Pandoc
Markdown.
Variables are specified with display math syntax, i.e.
\f[C]$$var$$\f[] in a template will be replaced with value of variable
\f[C]var\f[].
Variables can be specified in YAML metadata block, or from command line
(with \f[C]\-M\f[] switch).
There are two special variables, that are set internally:
.IP \[bu] 2
\f[C]i\f[] \-\- object number, possibly with chapter number (if
\f[C]chapter=True\f[])
.IP \[bu] 2
\f[C]t\f[] \-\- object caption, as given in source Markdown
.PP
Also there is a number of specific variables that are meaningful only in
certain contexts:
.IP \[bu] 2
\f[C]ccs\f[] \-\- collected subfigure captions.
Only applicable to \f[C]subfigureTemplate\f[].
Collected captions will be separated by \f[C]ccsDelim\f[] and individual
captions will be printed with \f[C]ccsTemplate\f[].
See Subfigures (#subfigures)
.IP \[bu] 2
\f[C]suf\f[] \-\- reference suffix, applicable to
\f[C]refIndexTemplate\f[], \f[C]subfigureRefIndexTemplate\f[]
.IP \[bu] 2
\f[C]s\f[] \-\- subfigure index, applicable to
\f[C]subfigureRefIndexTemplate\f[]
.PP
\f[C]xPrefixTemplate\f[], where \f[C]x\f[] is \f[C]fig\f[],
\f[C]eqn\f[], etc, are a special case.
Those don\[aq]t have \f[C]t\f[] variable, since there is no caption in
source markdown, but instead have \f[C]p\f[] variable, that binds to
relevant \f[C]xPrefix\f[].
This is done this way, since actual prefix vaule can depend on
\f[C]i\f[].
.PP
Please note that at the moment, templates are not supported with
LaTeX/PDF output.
.SS Custom Numbering Schemes
.PP
It\[aq]s possible to use other numbering schemes apart from arabic.
This is controlled by several metadata options, consult
Customization (#customization) for a list.
Possible values are:
.IP \[bu] 2
\f[C]arabic\f[] \-\- arabic numbers (1, 2, 3 ...)
.IP \[bu] 2
\f[C]roman\f[] \-\- roman numbers (I, II, III, IV, ...)
.IP \[bu] 2
\f[C]alpha\ x\f[], where \f[C]x\f[] is first letter to start from.
This will work for any letter, but will use UTF\-8 codepage to determine
what\[aq]s next, so using something strange is not advised.
For example, you can safely use \f[C]alpha\ a\f[] to get lowercase latin
letters for 26 figures.
After that, it will get weird (since basic latin alphabet has 26
letters).
Specifically, it will go into characters space (\f[C]{\f[], \f[C]|\f[],
\f[C]}\f[], etc).
You can consult
http://www.fileformat.info/info/unicode/block/basic_latin/utf8test.htm
for general idea on letter progression.
.IP \[bu] 2
list of strings.
You can define a YAML array for numbers.
Mapping is 1:1.
For example,
.RS 2
.IP
.nf
\f[C]
figLabels:\ [α,\ β,\ γ,\ 1,\ 2,\ 3,\ I,\ II,\ III]
\f[]
.fi
.PP
will give first figure label \[aq]α\[aq], second \-\- \[aq]β\[aq], etc.
.PP
Note that it will repeat last item in list indefinitely if there are
more images than items in list.
.RE
.SS Settings file
.PP
It is also possible to set variables used by pandoc\-crossref with a
separate YAML file.
If a given variable is not set in metadata, then pandoc\-crossref will
attempt to read it from file specified by \f[C]crossrefYaml\f[] metadata
variable, or, if not set, from \f[C]pandoc\-crossref.yaml\f[] from
current working directory.
This allows for reusable configurations.
One possible application is ad\-hoc internationalization.
.PP
For example, consider \f[C]$HOME/misc/pandoc\-crossref\-es.yaml\f[]:
.IP
.nf
\f[C]
figureTitle:\ "Figura"
tableTitle:\ "Tabla"
figPrefix:\ "fig."
eqnPrefix:\ "ec."
tblPrefix:\ "tbl."
loftitle:\ "#\ Lista\ de\ figuras"
lotTitle:\ "#\ Lista\ de\ tablas"
\f[]
.fi
.PP
pandoc\-crossref will send this data to pandoc wrapped in lines of
\f[C]\-\-\-\f[].
The YAML file\[aq]s first line should specify a variable; it will not
pass the variables if it is \f[C]\-\-\-\f[] or a blank line.
.PP
One could use this with pandoc\-crossref as follows:
.PP
\f[C]pandoc\ \-F\ pandoc\-crossref.hs\ \-M\ "crossrefYaml=$HOME/misc/pandoc\-crossref\-es.yaml"\f[]
.PP
You can also use global configuration files, which are expected in
\f[C]$HOME/.pandoc\-crossref/config.yaml\f[] and
\f[C]$HOME/.pandoc\-crossref/config\-$FORMAT.yaml\f[], where
\f[C]$FORMAT\f[] is output format, f.ex.
\f[C]latex\f[] or \f[C]epub\f[].
On Windows, \f[C]$HOME\f[] in general resolves to user\[aq]s root
directory, e.g.
\f[C]C:\\Users\\username\\\f[].
.PP
Priorities are as follows (from highest to lowest):
.IP \[bu] 2
document metadata
.IP \[bu] 2
\f[C]crossrefYaml\f[]/\f[C]$CWD/pandoc\-crossref.yaml\f[]
.IP \[bu] 2
\f[C]$HOME/.pandoc\-crossref/config\-$FORMAT.yaml\f[]
.IP \[bu] 2
\f[C]$HOME/.pandoc\-crossref/config.yaml\f[]
.SH License
.PP
This software is licensed under GNU GPL 2.
See
LICENSE.md (https://github.com/lierdakil/pandoc-crossref/blob/master/LICENSE.md)
for details.
.PP
© 2016 Nikolay Yakimov et al
.PP
Contributors (per GPL, holders of copyright on their respective
contributions):
.IP \[bu] 2
Nikolay Yakimov
.IP \[bu] 2
Felix Yan
.IP \[bu] 2
Wlad
.IP \[bu] 2
scoavoux
.IP \[bu] 2
Matthew Salganik
.IP \[bu] 2
Masamichi Hosoda
.IP \[bu] 2
Hadrien Mary
.IP \[bu] 2
Chris Black
.IP \[bu] 2
Bart Mesuere
.SH AUTHORS
Nikolay Yakimov.