Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Revise variables discussion in README.

Browse source
This commit is contained in:
Andrew Dunning 2015-10-05 18:47:58 -04:00
parent 869e800bbb
commit 317a5441a8
1 changed files with 81 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
README
View file

@ -124,12 +124,8 @@ will only be included if you use the `-s/--standalone` option.
Creating a PDF Creating a PDF
-------------- --------------
Earlier versions of pandoc came with a program, `markdown2pdf`, that To produce a PDF, specify an output file with a `.pdf` extension.
used pandoc and pdflatex to produce a PDF. This is no longer needed, Pandoc will use LaTeX to convert it to PDF:
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:
pandoc test.txt -o test.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 available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`, `--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
`graphicx` and `grffile` (if the document contains images), `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` `fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
and `xunicode` (if `xelatex` is used). and `xunicode` (if `xelatex` is used).
@ -195,7 +191,7 @@ General options
`json` (JSON version of native AST), `plain` (plain text), `json` (JSON version of native AST), `plain` (plain text),
`markdown` (pandoc's extended markdown), `markdown_strict` `markdown` (pandoc's extended markdown), `markdown_strict`
(original unextended markdown), `markdown_phpextra` (PHP Markdown (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` markdown), `commonmark` (CommonMark markdown), `rst`
(reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex` (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
(LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt), (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. : Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory 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 $HOME/.pandoc
in unix, in Windows XP:
C:\Documents And Settings\USERNAME\Application Data\pandoc C:\Documents And Settings\USERNAME\Application Data\pandoc
in Windows XP, and and in Windows Vista or later:
C:\Users\USERNAME\AppData\Roaming\pandoc C:\Users\USERNAME\AppData\Roaming\pandoc
in Windows 7. (You can find the default user data directory You can find the default user data directory on your system by
on your system by looking at the output of `pandoc --version`.) looking at the output of `pandoc --version`.
A `reference.odt`, `reference.docx`, `epub.css`, `templates`, A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
`slidy`, `slideous`, or `s5` directory `slidy`, `slideous`, or `s5` directory
placed in this directory will override pandoc's normal defaults. 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`: with pandoc, add this to your `.bashrc`:
eval "$(pandoc --bash-completion)" eval "$(pandoc --bash-completion)"
@ -379,7 +375,7 @@ Reader options
`--track-changes=accept`|`reject`|`all` `--track-changes=accept`|`reject`|`all`
: Specifies what to do with insertions and deletions produced by the MS : 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 insertions, and ignores all deletions. `reject` inserts all
deletions and ignores insertions. `all` puts in both insertions deletions and ignores insertions. `all` puts in both insertions
and deletions, wrapped in spans with `insertion` and `deletion` and deletions, wrapped in spans with `insertion` and `deletion`
@ -545,8 +541,8 @@ Options affecting specific writers
`--chapters` `--chapters`
: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook : Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
output. When the LaTeX template uses the report, book, or output. When the LaTeX document class is set to `report`, `book`, or
memoir class, this option is implied. If `beamer` is the output `memoir`, this option is implied. If `beamer` is the output
format, top-level headers will become `\part{..}`. format, top-level headers will become `\part{..}`.
`-N`, `--number-sections` `-N`, `--number-sections`
@ -572,7 +568,7 @@ Options affecting specific writers
: Do not convert quotation marks, apostrophes, and dashes to : Do not convert quotation marks, apostrophes, and dashes to
the TeX ligatures when writing LaTeX or ConTeXt. Instead, just the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
use literal unicode characters. This is needed for using advanced 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 `--smart` is selected automatically for LaTeX and ConTeXt
output, but it must be specified explicitly if `--no-tex-ligatures` output, but it must be specified explicitly if `--no-tex-ligatures`
is selected. If you use literal curly quotes, dashes, and ellipses is selected. If you use literal curly quotes, dashes, and ellipses
@ -581,7 +577,7 @@ Options affecting specific writers
`--listings` `--listings`
: Use listings package for LaTeX code blocks : Use the `listings` package for LaTeX code blocks
`-i`, `--incremental` `-i`, `--incremental`
@ -787,15 +783,13 @@ Citation rendering
: Use natbib for citations in LaTeX output. This option is not for use : 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 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 use in producing a LaTeX file that can be processed with bibtex.
bibtex.
`--biblatex` `--biblatex`
: Use biblatex for citations in LaTeX output. This option is not for use : 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 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 use in producing a LaTeX file that can be processed with bibtex or biber.
bibtex or biber.
Math rendering in HTML 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 add header and footer material that is needed for a self-standing
document. To see the default template that is used, just type 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 can be specified using the `--template` option. You can also override
the system default templates for a given output format `FORMAT` the system default templates for a given output format *FORMAT*
by putting a file `templates/default.FORMAT` in the user data by putting a file `templates/default.*FORMAT*` in the user data
directory (see `--data-dir`, above). *Exceptions:* For `odt` output, directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
customize the `default.opendocument` template. For `pdf` output, customize the `default.opendocument` template. For `pdf` output,
customize the `default.latex` template. customize the `default.latex` template.
Templates may contain *variables*. Variable names are sequences of Templates contain *variables*, which allow for the inclusion of
alphanumerics, `-`, and `_`, starting with a letter. A variable name arbitrary information at any point in the file. Variables may be set
surrounded by `$` signs will be replaced by its value. For example, within the document using YAML metadata. They may also be set at the
the string `$title$` in command line using the `-V/--variable` option: variables set in this
way override metadata fields with the same name.
<title>$title$</title> Variables set by pandoc
-----------------------
will be replaced by the document title.
To write a literal `$` in a template, use `$$`.
Some variables are set automatically by pandoc. These vary somewhat Some variables are set automatically by pandoc. These vary somewhat
depending on the output format, but include metadata fields (such 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`
: body of document : body of document
Language variables
------------------
`lang` `lang`
: The `lang` variable should be set by the user to a language : identifies the main language of the document,
code according to [BCP 47] (e.g. `en` or `en-GB`). using a code according to [BCP 47] (e.g. `en` or `en-GB`).
For some output formats, pandoc will convert it to an approriate For some output formats, pandoc will convert it to an appropriate
format stored in the additional variables `babel-lang`, format stored in the additional variables `babel-lang`,
`polyglossia-lang`, `polyglossia-variant` (LaTeX) `polyglossia-lang`, `polyglossia-variant` (LaTeX)
and `context-lang` (ConTeXt). and `context-lang` (ConTeXt).
`otherlangs` `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: in the YAML metadata, according to [BCP 47]. For example:
`otherlangs: [en-GB, fr]`. `otherlangs: [en-GB, fr]`.
Currently only used by XeTeX through the generated Currently only used by `xelatex` through the generated
`polyglossia-otherlangs` variable. `polyglossia-otherlangs` variable.
`dir` `dir`
@ -970,13 +965,15 @@ as `title`, `author`, and `date`) as well as the following:
(e.g. the browser, when generating HTML) supports the (e.g. the browser, when generating HTML) supports the
[Unicode Bidirectional Algorithm][uba-basics]. [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`). is fully supported (see `--latex-engine`).
Setting the `dir` variable enables bidirectional text Setting the `dir` variable enables bidirectional text
handling in LaTeX and ConTeXt, thus even if the base direction handling in LaTeX and ConTeXt: set `dir: ltr` for
is the default left-to-right, you should set `dir: ltr` for documents that also contain some right-to-left script,
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` `slidy-url`
: base URL for Slidy documents (defaults to : base URL for Slidy documents (defaults to
@ -997,22 +994,26 @@ as `title`, `author`, and `date`) as well as the following:
`transition` `transition`
: reveal.js transition : reveal.js transition
Variables for LaTeX
-------------------
`fontsize` `fontsize`
: font size (10pt, 11pt, 12pt) for LaTeX documents : font size (10pt, 11pt, 12pt) for LaTeX documents
`documentclass` `documentclass`
: document class for LaTeX documents : document class for LaTeX documents, e.g. `article`, `report`, `book`
`classoption` `classoption`
: option for LaTeX documentclass, e.g. `oneside`; may be repeated : option for LaTeX documentclass, e.g. `oneside`; may be repeated
for multiple options for multiple options
`geometry` `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 may be repeated for multiple options
`linestretch` `linestretch`
: adjusts line spacing (requires the `setspace` package) : adjusts line spacing in LaTeX documents using the `setspace`
package, e.g. `onehalfspacing`, `doublespacing`
`fontfamily` `fontfamily`
: font package to use for LaTeX documents (with pdflatex): : font package to use for LaTeX documents (with pdflatex):
@ -1023,23 +1024,28 @@ as `title`, `author`, and `date`) as well as the following:
and the default `lmodern`, among others. and the default `lmodern`, among others.
`fontfamilyoptions` `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` `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
: fonts for LaTeX documents (works only with xelatex : fonts for LaTeX documents (works only with `xelatex` and
and lualatex). Note that if `CJKmainfont` is used, `lualatex`): takes the name of any system font, using the
`fontspec` package. Note that if `CJKmainfont` is used,
the `xeCJK` package must be available. the `xeCJK` package must be available.
`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions` `mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
: options to use with `mainfont`, `sansfont`, `monofont`, : options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
`mathfont` in xelatex and lualatex. `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` `colortheme`, `fonttheme`, `innertheme`, `outertheme`
: themes for LaTeX beamer documents : themes for LaTeX beamer documents
`linkcolor` `linkcolor`
: color for internal links in LaTeX documents (`red`, `green`, : color for internal links in LaTeX documents, e.g. `red`, `green`,
`magenta`, `cyan`, `blue`, `black`) `magenta`, `cyan`, `blue`, `black`
`toccolor` `toccolor`
: color for links in table of contents in LaTeX documents : 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` `biblio-style`
: bibliography style in LaTeX, when used with `--natbib` : bibliography style in LaTeX, when used with `--natbib`
Variables for man pages
-----------------------
`section` `section`
: section number in man pages : section number in man pages
@ -1083,9 +1092,18 @@ as `title`, `author`, and `date`) as well as the following:
`footer` `footer`
: footer in man pages : footer in man pages
Variables may be set at the command line using the `-V/--variable` Using variables in templates
option. Variables set in this way override metadata fields with ----------------------------
the same name.
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: Templates may contain conditionals. The syntax is as follows:
@ -3485,7 +3503,7 @@ Hans-Peter Deifel,
Henry de Valence, Henry de Valence,
Ilya V. Portnov, Ilya V. Portnov,
infinity0x, infinity0x,
Jaime Marquínez Ferrándiz, Jaime Marquínez Ferrándiz,
James Aspnes, James Aspnes,
Jamie F. Olson, Jamie F. Olson,
Jan Larres, Jan Larres,
@ -3569,7 +3587,7 @@ Xavier Olive.
[HTML 5]: http://www.w3.org/TR/html5/ [HTML 5]: http://www.w3.org/TR/html5/
[XHTML]: http://www.w3.org/TR/xhtml1/ [XHTML]: http://www.w3.org/TR/xhtml1/
[LaTeX]: http://www.latex-project.org/ [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/ [ConTeXt]: http://www.pragma-ade.nl/
[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format [RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
[DocBook]: http://www.docbook.org/ [DocBook]: http://www.docbook.org/