@@ -124,12 +124,8 @@ will only be included if you use the `-s/--standalone` option.
124Creating a PDF
124Creating a PDF
125--------------
125--------------
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
127+To produce a PDF, specify an output file with a `.pdf` extension.
131−file and use pdflatex (or another engine, see `--latex-engine`) to convert it
128+Pandoc will use LaTeX to convert it to PDF:
134 pandoc test.txt -o test.pdf
130 pandoc test.txt -o test.pdf
@@ -138,7 +134,7 @@ Production of a PDF requires that a LaTeX engine be installed (see
138available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
134available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
139`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
135`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
140`graphicx` and `grffile` (if the document contains images),
136`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),
142`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
138`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
143and `xunicode` (if `xelatex` is used).
139and `xunicode` (if `xelatex` is used).
@@ -195,7 +191,7 @@ General options
195 `json` (JSON version of native AST), `plain` (plain text),
191 `json` (JSON version of native AST), `plain` (plain text),
196 `markdown` (pandoc's extended markdown), `markdown_strict`
192 `markdown` (pandoc's extended markdown), `markdown_strict`
197 (original unextended markdown), `markdown_phpextra` (PHP Markdown
193 (original unextended markdown), `markdown_phpextra` (PHP Markdown
198− extra extended markdown), `markdown_github` (github extended
194+ extra extended markdown), `markdown_github` (GitHub-flavored
199 markdown), `commonmark` (CommonMark markdown), `rst`
195 markdown), `commonmark` (CommonMark markdown), `rst`
200 (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
196 (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
201 (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
197 (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
@@ -232,27 +228,27 @@ General options
233: Specify the user data directory to search for pandoc data files.
229: Specify the user data directory to search for pandoc data files.
234 If this option is not specified, the default user data directory
230 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:
237 $HOME/.pandoc
233 $HOME/.pandoc
239− in unix,
235+ in Windows XP:
241 C:\Documents And Settings\USERNAME\Application Data\pandoc
237 C:\Documents And Settings\USERNAME\Application Data\pandoc
243− in Windows XP, and
239+ and in Windows Vista or later:
245 C:\Users\USERNAME\AppData\Roaming\pandoc
241 C:\Users\USERNAME\AppData\Roaming\pandoc
247− in Windows 7. (You can find the default user data directory
243+ You can find the default user data directory on your system by
248− on your system by looking at the output of `pandoc --version`.)
244+ looking at the output of `pandoc --version`.
249 A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
245 A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
250 `slidy`, `slideous`, or `s5` directory
246 `slidy`, `slideous`, or `s5` directory
251 placed in this directory will override pandoc's normal defaults.
247 placed in this directory will override pandoc's normal defaults.
253−`--bash-completiion`
249+`--bash-completion`
255−: Generate a bash completion script. to enable bash completion
251+: Generate a bash completion script. To enable bash completion
256 with pandoc, add this to your `.bashrc`:
252 with pandoc, add this to your `.bashrc`:
258 eval "$(pandoc --bash-completion)"
254 eval "$(pandoc --bash-completion)"
@@ -379,7 +375,7 @@ Reader options
379`--track-changes=accept`|`reject`|`all`
375`--track-changes=accept`|`reject`|`all`
381: Specifies what to do with insertions and deletions produced by the MS
377: 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
383 insertions, and ignores all deletions. `reject` inserts all
379 insertions, and ignores all deletions. `reject` inserts all
384 deletions and ignores insertions. `all` puts in both insertions
380 deletions and ignores insertions. `all` puts in both insertions
385 and deletions, wrapped in spans with `insertion` and `deletion`
381 and deletions, wrapped in spans with `insertion` and `deletion`
@@ -545,8 +541,8 @@ Options affecting specific writers
545`--chapters`
541`--chapters`
547: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
543: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
548− output. When the LaTeX template uses the report, book, or
544+ output. When the LaTeX document class is set to `report`, `book`, or
549− memoir class, this option is implied. If `beamer` is the output
545+ `memoir`, this option is implied. If `beamer` is the output
550 format, top-level headers will become `\part{..}`.
546 format, top-level headers will become `\part{..}`.
552`-N`, `--number-sections`
548`-N`, `--number-sections`
@@ -572,7 +568,7 @@ Options affecting specific writers
572: Do not convert quotation marks, apostrophes, and dashes to
568: Do not convert quotation marks, apostrophes, and dashes to
573 the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
569 the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
574 use literal unicode characters. This is needed for using advanced
570 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
576 `--smart` is selected automatically for LaTeX and ConTeXt
572 `--smart` is selected automatically for LaTeX and ConTeXt
577 output, but it must be specified explicitly if `--no-tex-ligatures`
573 output, but it must be specified explicitly if `--no-tex-ligatures`
578 is selected. If you use literal curly quotes, dashes, and ellipses
574 is selected. If you use literal curly quotes, dashes, and ellipses
@@ -581,7 +577,7 @@ Options affecting specific writers
582`--listings`
578`--listings`
584−: Use listings package for LaTeX code blocks
580+: Use the `listings` package for LaTeX code blocks
586`-i`, `--incremental`
582`-i`, `--incremental`
@@ -787,15 +783,13 @@ Citation rendering
788: Use natbib for citations in LaTeX output. This option is not for use
784: Use natbib for citations in LaTeX output. This option is not for use
789 with the `pandoc-citeproc` filter or with PDF output. It is intended for
785 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
786+ use in producing a LaTeX file that can be processed with bibtex.
793`--biblatex`
788`--biblatex`
795: Use biblatex for citations in LaTeX output. This option is not for use
790: Use biblatex for citations in LaTeX output. This option is not for use
796 with the `pandoc-citeproc` filter or with PDF output. It is intended for
791 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
792+ use in producing a LaTeX file that can be processed with bibtex or biber.
800Math rendering in HTML
794Math rendering in HTML
801----------------------
795----------------------
@@ -901,26 +895,24 @@ When the `-s/--standalone` option is used, pandoc uses a template to
901add header and footer material that is needed for a self-standing
895add header and footer material that is needed for a self-standing
902document. To see the default template that is used, just type
896document. To see the default template that is used, just type
904− pandoc -D FORMAT
898+ pandoc -D *FORMAT*
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
907can be specified using the `--template` option. You can also override
901can be specified using the `--template` option. You can also override
908−the system default templates for a given output format `FORMAT`
902+the system default templates for a given output format *FORMAT*
909−by putting a file `templates/default.FORMAT` in the user data
903+by putting a file `templates/default.*FORMAT*` in the user data
910directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
904directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
911customize the `default.opendocument` template. For `pdf` output,
905customize the `default.opendocument` template. For `pdf` output,
912customize the `default.latex` template.
906customize the `default.latex` template.
914−Templates may contain *variables*. Variable names are sequences of
908+Templates contain *variables*, which allow for the inclusion of
915−alphanumerics, `-`, and `_`, starting with a letter. A variable name
909+arbitrary information at any point in the file. Variables may be set
916−surrounded by `$` signs will be replaced by its value. For example,
910+within the document using YAML metadata. They may also be set at the
917−the string `$title$` in
911+command line using the `-V/--variable` option: variables set in this
912+way override metadata fields with the same name.
919− <title>$title$</title>
914+Variables set by pandoc
920−
915+-----------------------
921−will be replaced by the document title.
923−To write a literal `$` in a template, use `$$`.
925Some variables are set automatically by pandoc. These vary somewhat
917Some variables are set automatically by pandoc. These vary somewhat
926depending on the output format, but include metadata fields (such
918depending on the output format, but include metadata fields (such
@@ -944,19 +936,22 @@ as `title`, `author`, and `date`) as well as the following:
945: body of document
937: body of document
948−: The `lang` variable should be set by the user to a language
943+: identifies the main language of the document,
949− code according to [BCP 47] (e.g. `en` or `en-GB`).
944+ using a code according to [BCP 47] (e.g. `en` or `en-GB`).
950− For some output formats, pandoc will convert it to an approriate
945+ For some output formats, pandoc will convert it to an appropriate
951 format stored in the additional variables `babel-lang`,
946 format stored in the additional variables `babel-lang`,
952 `polyglossia-lang`, `polyglossia-variant` (LaTeX)
947 `polyglossia-lang`, `polyglossia-variant` (LaTeX)
953 and `context-lang` (ConTeXt).
948 and `context-lang` (ConTeXt).
955`otherlangs`
950`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
957 in the YAML metadata, according to [BCP 47]. For example:
952 in the YAML metadata, according to [BCP 47]. For example:
958 `otherlangs: [en-GB, fr]`.
953 `otherlangs: [en-GB, fr]`.
959− Currently only used by XeTeX through the generated
954+ Currently only used by `xelatex` through the generated
960 `polyglossia-otherlangs` variable.
955 `polyglossia-otherlangs` variable.
@@ -970,13 +965,15 @@ as `title`, `author`, and `date`) as well as the following:
970 (e.g. the browser, when generating HTML) supports the
965 (e.g. the browser, when generating HTML) supports the
971 [Unicode Bidirectional Algorithm][uba-basics].
966 [Unicode Bidirectional Algorithm][uba-basics].
973− When using LaTeX for bidi documents, only the XeLaTeX engine
968+ When using LaTeX for bidirectional documents, only the `xelatex` engine
974 is fully supported (see `--latex-engine`).
969 is fully supported (see `--latex-engine`).
975 Setting the `dir` variable enables bidirectional text
970 Setting the `dir` variable enables bidirectional text
976− handling in LaTeX and ConTeXt, thus even if the base direction
971+ handling in LaTeX and ConTeXt: set `dir: ltr` for
977− is the default left-to-right, you should set `dir: ltr` for
978− documents that also contain some right-to-left script.
972+ documents that also contain some right-to-left script,
973+ even if the base direction is the default left-to-right.
981`slidy-url`
978`slidy-url`
982: base URL for Slidy documents (defaults to
979: base URL for Slidy documents (defaults to
@@ -997,49 +994,58 @@ as `title`, `author`, and `date`) as well as the following:
997`transition`
994`transition`
998: reveal.js transition
995: reveal.js transition
1000`fontsize`
1000`fontsize`
1001: font size (10pt, 11pt, 12pt) for LaTeX documents
1001: font size (10pt, 11pt, 12pt) for LaTeX documents
1003`documentclass`
1003`documentclass`
1004−: document class for LaTeX documents
1004+: document class for LaTeX documents, e.g. `article`, `report`, `book`
1006`classoption`
1006`classoption`
1007: option for LaTeX documentclass, e.g. `oneside`; may be repeated
1007: option for LaTeX documentclass, e.g. `oneside`; may be repeated
1008 for multiple options
1008 for multiple options
1010`geometry`
1010`geometry`
1011−: options for LaTeX `geometry` class, e.g. `margin=1in`;
1011+: options for LaTeX `geometry` package, e.g. `margin=1in`;
1012 may be repeated for multiple options
1012 may be repeated for multiple options
1014`linestretch`
1014`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`
1017`fontfamily`
1018`fontfamily`
1018: font package to use for LaTeX documents (with pdflatex):
1019: 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),
1020 `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
1021 `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
1021 `mathpazo` or `pxfonts` or `mathpple` (Palatino),
1022 `mathpazo` or `pxfonts` or `mathpple` (Palatino),
1022 `libertine` (Linux Libertine), `arev` (Arev Sans),
1023 `libertine` (Linux Libertine), `arev` (Arev Sans),
1023 and the default `lmodern`, among others.
1024 and the default `lmodern`, among others.
1025`fontfamilyoptions`
1026`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
1028`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
1031`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
1029−: fonts for LaTeX documents (works only with xelatex
1032+: fonts for LaTeX documents (works only with `xelatex` and
1033+ `lualatex`): takes the name of any system font, using the
1030− and lualatex). Note that if `CJKmainfont` is used,
1034+ `fontspec` package. Note that if `CJKmainfont` is used,
1031 the `xeCJK` package must be available.
1035 the `xeCJK` package must be available.
1033−`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`
1037+`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
1034−: options to use with `mainfont`, `sansfont`, `monofont`,
1038+: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
1035− `mathfont` in xelatex and lualatex.
1039+ `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
1040+ available through `fontspec`, such as the OpenType features
1041+ `Numbers=OldStyle,Numbers=Proportional`.
1037`colortheme`, `fonttheme`, `innertheme`, `outertheme`
1043`colortheme`, `fonttheme`, `innertheme`, `outertheme`
1038: themes for LaTeX beamer documents
1044: themes for LaTeX beamer documents
1040`linkcolor`
1046`linkcolor`
1041−: color for internal links in LaTeX documents (`red`, `green`,
1047+: color for internal links in LaTeX documents, e.g. `red`, `green`,
1042− `magenta`, `cyan`, `blue`, `black`)
1048+ `magenta`, `cyan`, `blue`, `black`
1044`toccolor`
1050`toccolor`
1045: color for links in table of contents in LaTeX documents
1051: color for links in table of contents in LaTeX documents
@@ -1074,6 +1080,9 @@ as `title`, `author`, and `date`) as well as the following:
1074`biblio-style`
1080`biblio-style`
1075: bibliography style in LaTeX, when used with `--natbib`
1081: bibliography style in LaTeX, when used with `--natbib`
1083+Variables for man pages
1084+-----------------------
1077`section`
1086`section`
1078: section number in man pages
1087: section number in man pages
@@ -1083,9 +1092,18 @@ as `title`, `author`, and `date`) as well as the following:
1084: footer in man pages
1093: footer in man pages
1086−Variables may be set at the command line using the `-V/--variable`
1095+Using variables in templates
1087−option. Variables set in this way override metadata fields with
1096+----------------------------
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
1102+ <title>$title$</title>
1104+will be replaced by the document title.
1106+To write a literal `$` in a template, use `$$`.
1090Templates may contain conditionals. The syntax is as follows:
1108Templates may contain conditionals. The syntax is as follows:
@@ -3485,7 +3503,7 @@ Hans-Peter Deifel,
3485Henry de Valence,
3503Henry de Valence,
3486Ilya V. Portnov,
3504Ilya V. Portnov,
3487infinity0x,
3505infinity0x,
3488−Jaime Marquínez Ferrándiz,
3506+Jaime Marquínez Ferrándiz,
3489James Aspnes,
3507James Aspnes,
3490Jamie F. Olson,
3508Jamie F. Olson,
3491Jan Larres,
3509Jan Larres,
@@ -3569,7 +3587,7 @@ Xavier Olive.
3569[HTML 5]: http://www.w3.org/TR/html5/
3587[HTML 5]: http://www.w3.org/TR/html5/
3570[XHTML]: http://www.w3.org/TR/xhtml1/
3588[XHTML]: http://www.w3.org/TR/xhtml1/
3571[LaTeX]: http://www.latex-project.org/
3589[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
3573[ConTeXt]: http://www.pragma-ade.nl/
3591[ConTeXt]: http://www.pragma-ade.nl/
3574[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
3592[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
3575[DocBook]: http://www.docbook.org/
3593[DocBook]: http://www.docbook.org/