summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorAndrew Dunning <adunning@users.noreply.github.com>2015-10-05 18:47:58 -0400
committerAndrew Dunning <adunning@users.noreply.github.com>2015-10-05 18:47:58 -0400
commit317a5441a8ccd0226a339701da27fe57f2fc16a6 (patch)
tree7a6ea95c53430e6c42d83b8fc1f7873cd8ad784b /README
parent869e800bbbe4008beeb3e3420e689aafd6e67aa7 (diff)
Revise variables discussion in README.
Diffstat (limited to 'README')
-rw-r--r--README144
1 files changed, 81 insertions, 63 deletions
diff --git a/README b/README
index 9da70db5c..78e29002b 100644
--- a/README
+++ b/README
@@ -124,12 +124,8 @@ will only be included if you use the `-s/--standalone` option.
Creating a PDF
--------------
-Earlier versions of pandoc came with a program, `markdown2pdf`, that
-used pandoc and pdflatex to produce a PDF. This is no longer needed,
-since `pandoc` can now produce `pdf` output itself. To produce a PDF, simply
-specify an output file with a `.pdf` extension. Pandoc will create a latex
-file and use pdflatex (or another engine, see `--latex-engine`) to convert it
-to PDF:
+To produce a PDF, specify an output file with a `.pdf` extension.
+Pandoc will use LaTeX to convert it to PDF:
pandoc test.txt -o test.pdf
@@ -138,7 +134,7 @@ Production of a PDF requires that a LaTeX engine be installed (see
available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
`graphicx` and `grffile` (if the document contains images),
- `hyperref`, `ulem`, `babel` (if the `lang` variable is set),
+`hyperref`, `ulem`, `babel` and `polyglossia` (if the `lang` variable is set),
`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
and `xunicode` (if `xelatex` is used).
@@ -195,7 +191,7 @@ General options
`json` (JSON version of native AST), `plain` (plain text),
`markdown` (pandoc's extended markdown), `markdown_strict`
(original unextended markdown), `markdown_phpextra` (PHP Markdown
- extra extended markdown), `markdown_github` (github extended
+ extra extended markdown), `markdown_github` (GitHub-flavored
markdown), `commonmark` (CommonMark markdown), `rst`
(reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
(LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
@@ -232,27 +228,27 @@ General options
: Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory
- will be used. This is
+ will be used. This is, in Unix:
$HOME/.pandoc
- in unix,
+ in Windows XP:
C:\Documents And Settings\USERNAME\Application Data\pandoc
- in Windows XP, and
+ and in Windows Vista or later:
C:\Users\USERNAME\AppData\Roaming\pandoc
- in Windows 7. (You can find the default user data directory
- on your system by looking at the output of `pandoc --version`.)
+ You can find the default user data directory on your system by
+ looking at the output of `pandoc --version`.
A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
`slidy`, `slideous`, or `s5` directory
placed in this directory will override pandoc's normal defaults.
-`--bash-completiion`
+`--bash-completion`
-: Generate a bash completion script. to enable bash completion
+: Generate a bash completion script. To enable bash completion
with pandoc, add this to your `.bashrc`:
eval "$(pandoc --bash-completion)"
@@ -379,7 +375,7 @@ Reader options
`--track-changes=accept`|`reject`|`all`
: Specifies what to do with insertions and deletions produced by the MS
- Word "track-changes" feature. `accept` (the default), inserts all
+ Word "Track Changes" feature. `accept` (the default), inserts all
insertions, and ignores all deletions. `reject` inserts all
deletions and ignores insertions. `all` puts in both insertions
and deletions, wrapped in spans with `insertion` and `deletion`
@@ -545,8 +541,8 @@ Options affecting specific writers
`--chapters`
: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
- output. When the LaTeX template uses the report, book, or
- memoir class, this option is implied. If `beamer` is the output
+ output. When the LaTeX document class is set to `report`, `book`, or
+ `memoir`, this option is implied. If `beamer` is the output
format, top-level headers will become `\part{..}`.
`-N`, `--number-sections`
@@ -572,7 +568,7 @@ Options affecting specific writers
: Do not convert quotation marks, apostrophes, and dashes to
the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
use literal unicode characters. This is needed for using advanced
- OpenType features with XeLaTeX and LuaLaTeX. Note: normally
+ OpenType features with `xelatex` and `lualatex`. Note: normally
`--smart` is selected automatically for LaTeX and ConTeXt
output, but it must be specified explicitly if `--no-tex-ligatures`
is selected. If you use literal curly quotes, dashes, and ellipses
@@ -581,7 +577,7 @@ Options affecting specific writers
`--listings`
-: Use listings package for LaTeX code blocks
+: Use the `listings` package for LaTeX code blocks
`-i`, `--incremental`
@@ -787,15 +783,13 @@ Citation rendering
: Use natbib for citations in LaTeX output. This option is not for use
with the `pandoc-citeproc` filter or with PDF output. It is intended for
- use in producing a LaTeX file that can be processed with pdflatex and
- bibtex.
+ use in producing a LaTeX file that can be processed with bibtex.
`--biblatex`
: Use biblatex for citations in LaTeX output. This option is not for use
with the `pandoc-citeproc` filter or with PDF output. It is intended for
- use in producing a LaTeX file that can be processed with pdflatex and
- bibtex or biber.
+ use in producing a LaTeX file that can be processed with bibtex or biber.
Math rendering in HTML
----------------------
@@ -901,26 +895,24 @@ When the `-s/--standalone` option is used, pandoc uses a template to
add header and footer material that is needed for a self-standing
document. To see the default template that is used, just type
- pandoc -D FORMAT
+ pandoc -D *FORMAT*
-where `FORMAT` is the name of the output format. A custom template
+where *FORMAT* is the name of the output format. A custom template
can be specified using the `--template` option. You can also override
-the system default templates for a given output format `FORMAT`
-by putting a file `templates/default.FORMAT` in the user data
+the system default templates for a given output format *FORMAT*
+by putting a file `templates/default.*FORMAT*` in the user data
directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
customize the `default.opendocument` template. For `pdf` output,
customize the `default.latex` template.
-Templates may contain *variables*. Variable names are sequences of
-alphanumerics, `-`, and `_`, starting with a letter. A variable name
-surrounded by `$` signs will be replaced by its value. For example,
-the string `$title$` in
+Templates contain *variables*, which allow for the inclusion of
+arbitrary information at any point in the file. Variables may be set
+within the document using YAML metadata. They may also be set at the
+command line using the `-V/--variable` option: variables set in this
+way override metadata fields with the same name.
- <title>$title$</title>
-
-will be replaced by the document title.
-
-To write a literal `$` in a template, use `$$`.
+Variables set by pandoc
+-----------------------
Some variables are set automatically by pandoc. These vary somewhat
depending on the output format, but include metadata fields (such
@@ -944,19 +936,22 @@ as `title`, `author`, and `date`) as well as the following:
`body`
: body of document
+Language variables
+------------------
+
`lang`
-: The `lang` variable should be set by the user to a language
- code according to [BCP 47] (e.g. `en` or `en-GB`).
- For some output formats, pandoc will convert it to an approriate
+: identifies the main language of the document,
+ using a code according to [BCP 47] (e.g. `en` or `en-GB`).
+ For some output formats, pandoc will convert it to an appropriate
format stored in the additional variables `babel-lang`,
`polyglossia-lang`, `polyglossia-variant` (LaTeX)
and `context-lang` (ConTeXt).
`otherlangs`
-: Should be set to a list of other languages used in the document
+: a list of other languages used in the document
in the YAML metadata, according to [BCP 47]. For example:
`otherlangs: [en-GB, fr]`.
- Currently only used by XeTeX through the generated
+ Currently only used by `xelatex` through the generated
`polyglossia-otherlangs` variable.
`dir`
@@ -970,13 +965,15 @@ as `title`, `author`, and `date`) as well as the following:
(e.g. the browser, when generating HTML) supports the
[Unicode Bidirectional Algorithm][uba-basics].
- When using LaTeX for bidi documents, only the XeLaTeX engine
+ When using LaTeX for bidirectional documents, only the `xelatex` engine
is fully supported (see `--latex-engine`).
Setting the `dir` variable enables bidirectional text
- handling in LaTeX and ConTeXt, thus even if the base direction
- is the default left-to-right, you should set `dir: ltr` for
- documents that also contain some right-to-left script.
+ handling in LaTeX and ConTeXt: set `dir: ltr` for
+ documents that also contain some right-to-left script,
+ even if the base direction is the default left-to-right.
+Variables for slides
+--------------------
`slidy-url`
: base URL for Slidy documents (defaults to
@@ -997,49 +994,58 @@ as `title`, `author`, and `date`) as well as the following:
`transition`
: reveal.js transition
+Variables for LaTeX
+-------------------
+
`fontsize`
: font size (10pt, 11pt, 12pt) for LaTeX documents
`documentclass`
-: document class for LaTeX documents
+: document class for LaTeX documents, e.g. `article`, `report`, `book`
`classoption`
: option for LaTeX documentclass, e.g. `oneside`; may be repeated
for multiple options
`geometry`
-: options for LaTeX `geometry` class, e.g. `margin=1in`;
+: options for LaTeX `geometry` package, e.g. `margin=1in`;
may be repeated for multiple options
`linestretch`
-: adjusts line spacing (requires the `setspace` package)
+: adjusts line spacing in LaTeX documents using the `setspace`
+ package, e.g. `onehalfspacing`, `doublespacing`
`fontfamily`
: font package to use for LaTeX documents (with pdflatex):
- TeXLive has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
+ TeX Live has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
`fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
`mathpazo` or `pxfonts` or `mathpple` (Palatino),
`libertine` (Linux Libertine), `arev` (Arev Sans),
and the default `lmodern`, among others.
`fontfamilyoptions`
-: options to use with `fontfamily`.
+: options to use with `fontfamily` package: e.g. `osf,sc` with
+ `fontfamily` set to `mathpazo` provides Palatino with old-style
+ figures and true small caps
`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
-: fonts for LaTeX documents (works only with xelatex
- and lualatex). Note that if `CJKmainfont` is used,
+: fonts for LaTeX documents (works only with `xelatex` and
+ `lualatex`): takes the name of any system font, using the
+ `fontspec` package. Note that if `CJKmainfont` is used,
the `xeCJK` package must be available.
-`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`
-: options to use with `mainfont`, `sansfont`, `monofont`,
- `mathfont` in xelatex and lualatex.
+`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
+: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
+ `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
+ available through `fontspec`, such as the OpenType features
+ `Numbers=OldStyle,Numbers=Proportional`.
`colortheme`, `fonttheme`, `innertheme`, `outertheme`
: themes for LaTeX beamer documents
`linkcolor`
-: color for internal links in LaTeX documents (`red`, `green`,
- `magenta`, `cyan`, `blue`, `black`)
+: color for internal links in LaTeX documents, e.g. `red`, `green`,
+ `magenta`, `cyan`, `blue`, `black`
`toccolor`
: color for links in table of contents in LaTeX documents
@@ -1074,6 +1080,9 @@ as `title`, `author`, and `date`) as well as the following:
`biblio-style`
: bibliography style in LaTeX, when used with `--natbib`
+Variables for man pages
+-----------------------
+
`section`
: section number in man pages
@@ -1083,9 +1092,18 @@ as `title`, `author`, and `date`) as well as the following:
`footer`
: footer in man pages
-Variables may be set at the command line using the `-V/--variable`
-option. Variables set in this way override metadata fields with
-the same name.
+Using variables in templates
+----------------------------
+
+Variable names are sequences of alphanumerics, `-`, and `_`,
+starting with a letter. A variable name surrounded by `$` signs
+will be replaced by its value. For example, the string `$title$` in
+
+ <title>$title$</title>
+
+will be replaced by the document title.
+
+To write a literal `$` in a template, use `$$`.
Templates may contain conditionals. The syntax is as follows:
@@ -3485,7 +3503,7 @@ Hans-Peter Deifel,
Henry de Valence,
Ilya V. Portnov,
infinity0x,
-Jaime Marquínez Ferrándiz,
+Jaime Marquínez Ferrándiz,
James Aspnes,
Jamie F. Olson,
Jan Larres,
@@ -3569,7 +3587,7 @@ Xavier Olive.
[HTML 5]: http://www.w3.org/TR/html5/
[XHTML]: http://www.w3.org/TR/xhtml1/
[LaTeX]: http://www.latex-project.org/
-[beamer]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/beamer
+[beamer]: https://ctan.org/pkg/beamer
[ConTeXt]: http://www.pragma-ade.nl/
[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
[DocBook]: http://www.docbook.org/