@@ -124,12 +124,8 @@ will only be included if you use the `-s/--standalone` option.
124124Creating a PDF
125125--------------
126126
127−Earlier versions of pandoc came with a program, `markdown2pdf`, that
128−used pandoc and pdflatex to produce a PDF. This is no longer needed,
129−since `pandoc` can now produce `pdf` output itself. To produce a PDF, simply
130−specify an output file with a `.pdf` extension. Pandoc will create a latex
131−file and use pdflatex (or another engine, see `--latex-engine`) to convert it
132−to PDF:
127+To produce a PDF, specify an output file with a `.pdf` extension.
128+Pandoc will use LaTeX to convert it to PDF:
133129
134130 pandoc test.txt -o test.pdf
135131
@@ -138,7 +134,7 @@ Production of a PDF requires that a LaTeX engine be installed (see
138134available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
139135`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
140136`graphicx` and `grffile` (if the document contains images),
141− `hyperref`, `ulem`, `babel` (if the `lang` variable is set),
137+`hyperref`, `ulem`, `babel` and `polyglossia` (if the `lang` variable is set),
142138`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
143139and `xunicode` (if `xelatex` is used).
144140
@@ -195,7 +191,7 @@ General options
195191 `json` (JSON version of native AST), `plain` (plain text),
196192 `markdown` (pandoc's extended markdown), `markdown_strict`
197193 (original unextended markdown), `markdown_phpextra` (PHP Markdown
198− extra extended markdown), `markdown_github` (github extended
194+ extra extended markdown), `markdown_github` (GitHub-flavored
199195 markdown), `commonmark` (CommonMark markdown), `rst`
200196 (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
201197 (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
@@ -232,27 +228,27 @@ General options
232228
233229: Specify the user data directory to search for pandoc data files.
234230 If this option is not specified, the default user data directory
235− will be used. This is
231+ will be used. This is, in Unix:
236232
237233 $HOME/.pandoc
238234
239− in unix,
235+ in Windows XP:
240236
241237 C:\Documents And Settings\USERNAME\Application Data\pandoc
242238
243− in Windows XP, and
239+ and in Windows Vista or later:
244240
245241 C:\Users\USERNAME\AppData\Roaming\pandoc
246242
247− in Windows 7. (You can find the default user data directory
248− on your system by looking at the output of `pandoc --version`.)
243+ You can find the default user data directory on your system by
244+ looking at the output of `pandoc --version`.
249245 A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
250246 `slidy`, `slideous`, or `s5` directory
251247 placed in this directory will override pandoc's normal defaults.
252248
253−`--bash-completiion`
249+`--bash-completion`
254250
255−: Generate a bash completion script. to enable bash completion
251+: Generate a bash completion script. To enable bash completion
256252 with pandoc, add this to your `.bashrc`:
257253
258254 eval "$(pandoc --bash-completion)"
@@ -379,7 +375,7 @@ Reader options
379375`--track-changes=accept`|`reject`|`all`
380376
381377: Specifies what to do with insertions and deletions produced by the MS
382− Word "track-changes" feature. `accept` (the default), inserts all
378+ Word "Track Changes" feature. `accept` (the default), inserts all
383379 insertions, and ignores all deletions. `reject` inserts all
384380 deletions and ignores insertions. `all` puts in both insertions
385381 and deletions, wrapped in spans with `insertion` and `deletion`
@@ -545,8 +541,8 @@ Options affecting specific writers
545541`--chapters`
546542
547543: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
548− output. When the LaTeX template uses the report, book, or
549− memoir class, this option is implied. If `beamer` is the output
544+ output. When the LaTeX document class is set to `report`, `book`, or
545+ `memoir`, this option is implied. If `beamer` is the output
550546 format, top-level headers will become `\part{..}`.
551547
552548`-N`, `--number-sections`
@@ -572,7 +568,7 @@ Options affecting specific writers
572568: Do not convert quotation marks, apostrophes, and dashes to
573569 the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
574570 use literal unicode characters. This is needed for using advanced
575− OpenType features with XeLaTeX and LuaLaTeX. Note: normally
571+ OpenType features with `xelatex` and `lualatex`. Note: normally
576572 `--smart` is selected automatically for LaTeX and ConTeXt
577573 output, but it must be specified explicitly if `--no-tex-ligatures`
578574 is selected. If you use literal curly quotes, dashes, and ellipses
@@ -581,7 +577,7 @@ Options affecting specific writers
581577
582578`--listings`
583579
584−: Use listings package for LaTeX code blocks
580+: Use the `listings` package for LaTeX code blocks
585581
586582`-i`, `--incremental`
587583
@@ -787,15 +783,13 @@ Citation rendering
787783
788784: Use natbib for citations in LaTeX output. This option is not for use
789785 with the `pandoc-citeproc` filter or with PDF output. It is intended for
790− use in producing a LaTeX file that can be processed with pdflatex and
791− bibtex.
786+ use in producing a LaTeX file that can be processed with bibtex.
792787
793788`--biblatex`
794789
795790: Use biblatex for citations in LaTeX output. This option is not for use
796791 with the `pandoc-citeproc` filter or with PDF output. It is intended for
797− use in producing a LaTeX file that can be processed with pdflatex and
798− bibtex or biber.
792+ use in producing a LaTeX file that can be processed with bibtex or biber.
799793
800794Math rendering in HTML
801795----------------------
@@ -901,26 +895,24 @@ When the `-s/--standalone` option is used, pandoc uses a template to
901895add header and footer material that is needed for a self-standing
902896document. To see the default template that is used, just type
903897
904− pandoc -D FORMAT
898+ pandoc -D *FORMAT*
905899
906−where `FORMAT` is the name of the output format. A custom template
900+where *FORMAT* is the name of the output format. A custom template
907901can be specified using the `--template` option. You can also override
908−the system default templates for a given output format `FORMAT`
909−by putting a file `templates/default.FORMAT` in the user data
902+the system default templates for a given output format *FORMAT*
903+by putting a file `templates/default.*FORMAT*` in the user data
910904directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
911905customize the `default.opendocument` template. For `pdf` output,
912906customize the `default.latex` template.
913907
914−Templates may contain *variables*. Variable names are sequences of
915−alphanumerics, `-`, and `_`, starting with a letter. A variable name
916−surrounded by `$` signs will be replaced by its value. For example,
917−the string `$title$` in
908+Templates contain *variables*, which allow for the inclusion of
909+arbitrary information at any point in the file. Variables may be set
910+within the document using YAML metadata. They may also be set at the
911+command line using the `-V/--variable` option: variables set in this
912+way override metadata fields with the same name.
918913
919− <title>$title$</title>
920−
921−will be replaced by the document title.
922−
923−To write a literal `$` in a template, use `$$`.
914+Variables set by pandoc
915+-----------------------
924916
925917Some variables are set automatically by pandoc. These vary somewhat
926918depending on the output format, but include metadata fields (such
@@ -944,19 +936,22 @@ as `title`, `author`, and `date`) as well as the following:
944936`body`
945937: body of document
946938
939+Language variables
940+------------------
941+
947942`lang`
948−: The `lang` variable should be set by the user to a language
949− code according to [BCP 47] (e.g. `en` or `en-GB`).
950− For some output formats, pandoc will convert it to an approriate
943+: identifies the main language of the document,
944+ using a code according to [BCP 47] (e.g. `en` or `en-GB`).
945+ For some output formats, pandoc will convert it to an appropriate
951946 format stored in the additional variables `babel-lang`,
952947 `polyglossia-lang`, `polyglossia-variant` (LaTeX)
953948 and `context-lang` (ConTeXt).
954949
955950`otherlangs`
956−: Should be set to a list of other languages used in the document
951+: a list of other languages used in the document
957952 in the YAML metadata, according to [BCP 47]. For example:
958953 `otherlangs: [en-GB, fr]`.
959− Currently only used by XeTeX through the generated
954+ Currently only used by `xelatex` through the generated
960955 `polyglossia-otherlangs` variable.
961956
962957`dir`
@@ -970,13 +965,15 @@ as `title`, `author`, and `date`) as well as the following:
970965 (e.g. the browser, when generating HTML) supports the
971966 [Unicode Bidirectional Algorithm][uba-basics].
972967
973− When using LaTeX for bidi documents, only the XeLaTeX engine
968+ When using LaTeX for bidirectional documents, only the `xelatex` engine
974969 is fully supported (see `--latex-engine`).
975970 Setting the `dir` variable enables bidirectional text
976− handling in LaTeX and ConTeXt, thus even if the base direction
977− is the default left-to-right, you should set `dir: ltr` for
978− documents that also contain some right-to-left script.
971+ handling in LaTeX and ConTeXt: set `dir: ltr` for
972+ documents that also contain some right-to-left script,
973+ even if the base direction is the default left-to-right.
979974
975+Variables for slides
976+--------------------
980977
981978`slidy-url`
982979: base URL for Slidy documents (defaults to
@@ -997,49 +994,58 @@ as `title`, `author`, and `date`) as well as the following:
997994`transition`
998995: reveal.js transition
999996
997+Variables for LaTeX
998+-------------------
999+
10001000`fontsize`
10011001: font size (10pt, 11pt, 12pt) for LaTeX documents
10021002
10031003`documentclass`
1004−: document class for LaTeX documents
1004+: document class for LaTeX documents, e.g. `article`, `report`, `book`
10051005
10061006`classoption`
10071007: option for LaTeX documentclass, e.g. `oneside`; may be repeated
10081008 for multiple options
10091009
10101010`geometry`
1011−: options for LaTeX `geometry` class, e.g. `margin=1in`;
1011+: options for LaTeX `geometry` package, e.g. `margin=1in`;
10121012 may be repeated for multiple options
10131013
10141014`linestretch`
1015−: adjusts line spacing (requires the `setspace` package)
1015+: adjusts line spacing in LaTeX documents using the `setspace`
1016+ package, e.g. `onehalfspacing`, `doublespacing`
10161017
10171018`fontfamily`
10181019: font package to use for LaTeX documents (with pdflatex):
1019− TeXLive has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
1020+ TeX Live has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
10201021 `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
10211022 `mathpazo` or `pxfonts` or `mathpple` (Palatino),
10221023 `libertine` (Linux Libertine), `arev` (Arev Sans),
10231024 and the default `lmodern`, among others.
10241025
10251026`fontfamilyoptions`
1026−: options to use with `fontfamily`.
1027+: options to use with `fontfamily` package: e.g. `osf,sc` with
1028+ `fontfamily` set to `mathpazo` provides Palatino with old-style
1029+ figures and true small caps
10271030
10281031`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
1029−: fonts for LaTeX documents (works only with xelatex
1030− and lualatex). Note that if `CJKmainfont` is used,
1032+: fonts for LaTeX documents (works only with `xelatex` and
1033+ `lualatex`): takes the name of any system font, using the
1034+ `fontspec` package. Note that if `CJKmainfont` is used,
10311035 the `xeCJK` package must be available.
10321036
1033−`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`
1034−: options to use with `mainfont`, `sansfont`, `monofont`,
1035− `mathfont` in xelatex and lualatex.
1037+`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
1038+: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
1039+ `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
1040+ available through `fontspec`, such as the OpenType features
1041+ `Numbers=OldStyle,Numbers=Proportional`.
10361042
10371043`colortheme`, `fonttheme`, `innertheme`, `outertheme`
10381044: themes for LaTeX beamer documents
10391045
10401046`linkcolor`
1041−: color for internal links in LaTeX documents (`red`, `green`,
1042− `magenta`, `cyan`, `blue`, `black`)
1047+: color for internal links in LaTeX documents, e.g. `red`, `green`,
1048+ `magenta`, `cyan`, `blue`, `black`
10431049
10441050`toccolor`
10451051: color for links in table of contents in LaTeX documents
@@ -1074,6 +1080,9 @@ as `title`, `author`, and `date`) as well as the following:
10741080`biblio-style`
10751081: bibliography style in LaTeX, when used with `--natbib`
10761082
1083+Variables for man pages
1084+-----------------------
1085+
10771086`section`
10781087: section number in man pages
10791088
@@ -1083,9 +1092,18 @@ as `title`, `author`, and `date`) as well as the following:
10831092`footer`
10841093: footer in man pages
10851094
1086−Variables may be set at the command line using the `-V/--variable`
1087−option. Variables set in this way override metadata fields with
1088−the same name.
1095+Using variables in templates
1096+----------------------------
1097+
1098+Variable names are sequences of alphanumerics, `-`, and `_`,
1099+starting with a letter. A variable name surrounded by `$` signs
1100+will be replaced by its value. For example, the string `$title$` in
1101+
1102+ <title>$title$</title>
1103+
1104+will be replaced by the document title.
1105+
1106+To write a literal `$` in a template, use `$$`.
10891107
10901108Templates may contain conditionals. The syntax is as follows:
10911109
@@ -3485,7 +3503,7 @@ Hans-Peter Deifel,
34853503Henry de Valence,
34863504Ilya V. Portnov,
34873505infinity0x,
3488−Jaime Marquínez Ferrándiz,
3506+Jaime Marquínez Ferrándiz,
34893507James Aspnes,
34903508Jamie F. Olson,
34913509Jan Larres,
@@ -3569,7 +3587,7 @@ Xavier Olive.
35693587[HTML 5]: http://www.w3.org/TR/html5/
35703588[XHTML]: http://www.w3.org/TR/xhtml1/
35713589[LaTeX]: http://www.latex-project.org/
3572−[beamer]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/beamer
3590+[beamer]: https://ctan.org/pkg/beamer
35733591[ConTeXt]: http://www.pragma-ade.nl/
35743592[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
35753593[DocBook]: http://www.docbook.org/