aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2021-03-08 07:45:23 -0800
committerJohn MacFarlane <jgm@berkeley.edu>2021-03-08 07:45:23 -0800
commit3a763ac7700770cfccd0dded11a7f6b82618ce1a (patch)
treecec169fffd51cde05abe22d78de5ba22621d498e
parent3e8546feedeaba19c56565c8c547b3ba4ce391af (diff)
downloadpandoc-3a763ac7700770cfccd0dded11a7f6b82618ce1a.tar.gz
Update date in changelog and manual.
-rw-r--r--MANUAL.txt2
-rw-r--r--changelog.md2
-rw-r--r--man/pandoc.160
3 files changed, 50 insertions, 14 deletions
diff --git a/MANUAL.txt b/MANUAL.txt
index a5036b361..9dfb2909b 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,7 +1,7 @@
---
title: Pandoc User's Guide
author: John MacFarlane
-date: March 4, 2021
+date: March 8, 2021
---
# Synopsis
diff --git a/changelog.md b/changelog.md
index 7e8276465..f06283ea2 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,6 +1,6 @@
# Revision history for pandoc
-## pandoc 2.12 (UNRELEASED -- PROVISIONAL)
+## pandoc 2.12 (2021-03-08)
* `--resource-path` now accumulates if specified multiple
times (#6152). Resource paths specified later on the command line are
diff --git a/man/pandoc.1 b/man/pandoc.1
index 71efe9d65..3ed6fcddb 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,7 +1,7 @@
'\" t
-.\" Automatically generated by Pandoc 2.11.4
+.\" Automatically generated by Pandoc 2.12
.\"
-.TH "Pandoc User\[cq]s Guide" "" "March 4, 2021" "pandoc 2.12" ""
+.TH "Pandoc User\[cq]s Guide" "" "March 8, 2021" "pandoc 2.12" ""
.hy
.SH NAME
pandoc - general markup converter
@@ -457,16 +457,15 @@ On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
variable).
-If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
-(for backwards compatibility).
-In Windows the default user data directory is
+If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it
+will be used (for backwards compatibility).
+On Windows the default user data directory is
\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
You can find the default user data directory on your system by looking
at the output of \f[C]pandoc --version\f[R].
-A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
-\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
-\f[C]s5\f[R] directory placed in this directory will override
-pandoc\[cq]s normal defaults.
+Data files placed in this directory (for example,
+\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
+\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.
.TP
\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
Specify a set of default option settings.
@@ -731,9 +730,9 @@ system default.
To see the system default, use
\f[C]pandoc --print-default-data-file=abbreviations\f[R].
The only use pandoc makes of this list is in the Markdown reader.
-Strings ending in a period that are found in this list will be followed
-by a nonbreaking space, so that the period will not produce
-sentence-ending space in formats like LaTeX.
+Strings found in this list will be followed by a nonbreaking space, and
+the period will not produce sentence-ending space in formats like LaTeX.
+The strings may not contain spaces.
.SS General writer options
.TP
\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
@@ -924,6 +923,11 @@ Note that, if \f[C]--resource-path\f[R] is specified, the working
directory must be explicitly listed or it will not be searched.
For example: \f[C]--resource-path=.:test\f[R] will search the working
directory and the \f[C]test\f[R] subdirectory, in that order.
+This option can be used repeatedly.
+Search path components that come later on the command line will be
+searched before those that come earlier, so
+\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent
+to \f[C]--resource-path baz:bim:foo:bar\f[R].
.TP
\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]
Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
@@ -1887,6 +1891,38 @@ verbosity: INFO
\f[R]
.fi
.PP
+In fields that expect a file path (or list of file paths), the following
+syntax may be used to interpolate environment variables:
+.IP
+.nf
+\f[C]
+csl: ${HOME}/mycsldir/special.csl
+\f[R]
+.fi
+.PP
+\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the
+user data directory that is current when the defaults file is parsed,
+regardless of the setting of the environment variable
+\f[C]USERDATA\f[R].
+.PP
+\f[C]${.}\f[R] will resolve to the directory containing the default file
+itself.
+This allows you to refer to resources contained in that directory:
+.IP
+.nf
+\f[C]
+epub-cover-image: ${.}/cover.jpg
+epub-metadata: ${.}/meta.xml
+resource-path:
+- . # the working directory from which pandoc is run
+- ${.}/images # the images subdirectory of the directory
+ # containing this defaults file
+\f[R]
+.fi
+.PP
+This environment variable interpolation syntax \f[I]only\f[R] works in
+fields that expect file paths.
+.PP
Default files can be placed in the \f[C]defaults\f[R] subdirectory of
the user data directory and used from any directory.
For example, one could create a file specifying defaults for writing