From a7a603cc04a7fc0a5ea9694f7e3b391a98d4a9f7 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Fri, 28 May 2021 15:13:22 -0700 Subject: Update manual. --- man/pandoc.1 | 47 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) (limited to 'man') diff --git a/man/pandoc.1 b/man/pandoc.1 index ac5479414..7eec066ab 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,7 +1,7 @@ '\" t .\" Automatically generated by Pandoc 2.14 .\" -.TH "Pandoc User\[cq]s Guide" "" "May 21, 2021" "pandoc 2.14" "" +.TH "Pandoc User\[cq]s Guide" "" "May 28, 2021" "pandoc 2.14" "" .hy .SH NAME pandoc - general markup converter @@ -4275,7 +4275,7 @@ Term 2 Note that space between items in a definition list is required. (A variant that loosens this requirement, but disallows \[lq]lazy\[rq] hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]: -see Non-pandoc extensions, below.) +see Non-default extensions, below.) .SS Numbered example lists .SS Extension: \f[C]example_lists\f[R] .PP @@ -5866,12 +5866,14 @@ singular or plural forms, as \f[C]book\f[R], If no locator term is used, \[lq]page\[rq] is assumed. .PP In complex cases, you can force something to be treated as a locator by -enclosing it in curly braces: +enclosing it in curly braces or prevent parsing the suffix as locator by +prepending curly braces: .IP .nf \f[C] [\[at]smith{ii, A, D-Z}, with a suffix] [\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here] +[\[at]smith{}, 99 years later] \f[R] .fi .PP @@ -5909,13 +5911,50 @@ normal citations will be put in parentheses, while author-in-text citations will not. For this reason, it is sometimes preferable to use the author-in-text style inside notes when using a note style. -.SS Non-pandoc extensions +.SS Non-default extensions .PP The following Markdown syntax extensions are not enabled by default in pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format name, where \f[C]EXTENSION\f[R] is the name of the extension. Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with hard line breaks. +.SS Extension: \f[C]rebase_relative_paths\f[R] +.PP +Rewrite relative paths for Markdown links and images, depending on the +path of the file containing the link or image link. +For each link or image, pandoc will compute the directory of the +containing file, relative to the working directory, and prepend the +resulting path to the link or image path. +.PP +The use of this extension is best understood by example. +Suppose you have a a subdirectory for each chapter of a book, +\f[C]chap1\f[R], \f[C]chap2\f[R], \f[C]chap3\f[R]. +Each contains a file \f[C]text.md\f[R] and a number of images used in +the chapter. +You would like to have \f[C]![image](spider.jpg)\f[R] in +\f[C]chap1/text.md\f[R] refer to \f[C]chap1/spider.jpg\f[R] and +\f[C]![image](spider.jpg)\f[R] in \f[C]chap2/text.md\f[R] refer to +\f[C]chap2/spider.jpg\f[R]. +To do this, use +.IP +.nf +\f[C] +pandoc chap*/*.md -f markdown+rebase_relative_paths +\f[R] +.fi +.PP +Without this extension, you would have to use +\f[C]![image](chap1/spider.jpg)\f[R] in \f[C]chap1/text.md\f[R] and +\f[C]![image](chap2/spider.jpg)\f[R] in \f[C]chap2/text.md\f[R]. +Links with relative paths will be rewritten in the same way as images. +.PP +Absolute paths and URLs are not changed. +Neither are empty paths or paths consisting entirely of a fragment, +e.g., \f[C]#foo\f[R]. +.PP +Note that relative paths in reference links and images will be rewritten +relative to the file containing the link reference definition, not the +file containing the reference link or image itself, if these differ. .SS Extension: \f[C]attributes\f[R] .PP Allows attributes to be attached to any inline or block-level element. -- cgit v1.2.3