diff options
| author | Andrew Dunning <adunning@users.noreply.github.com> | 2019-01-23 18:36:11 -0500 |
|---|---|---|
| committer | John MacFarlane <jgm@berkeley.edu> | 2019-01-23 15:36:11 -0800 |
| commit | e18d9ba5427c67a4a50675311ee180d54790a60a (patch) | |
| tree | cd6d26f587305cb2d42ddd70e7bf4dd4dfd438c2 | |
| parent | c5ccfabd9b998793d4f4b9a7488038900a0423cc (diff) | |
| download | pandoc-e18d9ba5427c67a4a50675311ee180d54790a60a.tar.gz | |
Manual: Reorganize template variables (#5249)
Add additional headings to categorize variables, and
alphabetize when there is large number; add more examples.
| -rw-r--r-- | MANUAL.txt | 513 |
1 files changed, 305 insertions, 208 deletions
diff --git a/MANUAL.txt b/MANUAL.txt index 3823f3eb6..9d26c61fa 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -128,12 +128,9 @@ To do this, specify an output file with a `.pdf` extension, as before, but add the `--pdf-engine` option or `-t context`, `-t html`, or `-t ms` to the command line (`-t html` defaults to `--pdf-engine=wkhtmltopdf`). -PDF output can be controlled using [variables for LaTeX] (if -LaTeX is used) and [variables for ConTeXt] (if ConTeXt is used). -When using an HTML/CSS-to-PDF-engine, `--css` affects the output. -If `wkhtmltopdf` is used, then the variables `margin-left`, -`margin-right`, `margin-top`, `margin-bottom`, `footer-html`, -`header-html` and `papersize` will affect the output. +PDF output uses [variables for LaTeX] (with a LaTeX engine); +[variables for ConTeXt] (with ConTeXt); or [variables for `wkhtmltopdf`] +(an HTML/CSS-to-PDF engine; `--css` also affects the output). To debug the PDF creation, it can be useful to look at the intermediate representation: instead of `-o test.pdf`, use for example `-s -o test.tex` @@ -1027,16 +1024,51 @@ Options affecting specific writers {.options} custom-reference.docx`. Then open `custom-reference.docx` in Word, modify the styles as you wish, and save the file. For best results, do not make changes to this file other - than modifying the styles used by pandoc: [paragraph] - Normal, Body Text, First Paragraph, Compact, Title, - Subtitle, Author, Date, Abstract, Bibliography, Heading 1, - Heading 2, Heading 3, Heading 4, Heading 5, Heading 6, - Heading 7, Heading 8, Heading 9, Block Text, Footnote Text, - Definition Term, Definition, Caption, Table Caption, - Image Caption, Figure, Captioned Figure, TOC Heading; - [character] Default Paragraph Font, Body Text Char, - Verbatim Char, Footnote Reference, Hyperlink; [table] - Table. + than modifying the styles used by pandoc: + + Paragraph styles: + + - Normal + - Body Text + - First Paragraph + - Compact + - Title + - Subtitle + - Author + - Date + - Abstract + - Bibliography + - Heading 1 + - Heading 2 + - Heading 3 + - Heading 4 + - Heading 5 + - Heading 6 + - Heading 7 + - Heading 8 + - Heading 9 + - Block Text + - Footnote Text + - Definition Term + - Definition + - Caption + - Table Caption + - Image Caption + - Figure + - Captioned Figure + - TOC Heading + + Character styles: + + - Default Paragraph Font + - Body Text Char + - Verbatim Char + - Footnote Reference + - Hyperlink + + Table style: + + - Table ODT @@ -1333,27 +1365,8 @@ pandoc will look for the key in the document's metadata – which can be set using either [YAML metadata blocks][Extension: `yaml_metadata_block`] or with the `--metadata` option. -Variables set by pandoc ------------------------ - -Some variables are set automatically by pandoc. These vary somewhat -depending on the output format, but include the following: - -`sourcefile`, `outputfile` -: source and destination filenames, as given on the command line. - `sourcefile` can also be a list if input comes from multiple files, or empty - if input is from stdin. You can use the following snippet in your template - to distinguish them: - - $if(sourcefile)$ - $for(sourcefile)$ - $sourcefile$ - $endfor$ - $else$ - (stdin) - $endif$ - - Similarly, `outputfile` can be `-` if output goes to the terminal. +Metadata variables +------------------ `title`, `author`, `date` : allow identification of basic aspects of the document. Included @@ -1375,53 +1388,35 @@ depending on the output format, but include the following: `keywords` : list of keywords to be included in HTML, PDF, and AsciiDoc metadata; - may be repeated as for `author`, above - -`header-includes` -: contents specified by `-H/--include-in-header` (may have multiple - values) - -`toc` -: non-null value if `--toc/--table-of-contents` was specified - -`toc-title` -: title of table of contents (works only with EPUB, - opendocument, odt, docx, pptx, beamer, LaTeX) - -`include-before` -: contents specified by `-B/--include-before-body` (may have - multiple values) - -`include-after` -: contents specified by `-A/--include-after-body` (may have - multiple values) - -`body` -: body of document - -`meta-json` -: JSON representation of all of the document's metadata. Field - values are transformed to the selected output format. + repeat as for `author`, above Language variables ------------------ `lang` -: 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` (LaTeX) and `context-lang` (ConTeXt). - - Native pandoc Spans and Divs with the lang attribute - (value in BCP 47) can be used to switch the language in - that range. In LaTeX output, `babel-otherlangs` and - `polyglossia-otherlangs` variables will be generated - automatically based on the `lang` attributes of Spans - and Divs in the document. +: identifies the main language of the document using IETF language + tags (following the [BCP 47] standard), such as `en` or `en-GB`. + The [Language subtag lookup] tool can look up or verify these tags. + This affects most formats, and controls hyphenation in PDF output + when using LaTeX (through [`babel`] and [`polyglossia`]) or ConTeXt. + + Use native pandoc [Divs and Spans] with the `lang` attribute to + switch the language: + + --- + lang: en-GB + ... + + Text in the main document language (British English). + ::: {lang=fr-CA} + > Cette citation est écrite en français canadien. + ::: + + More text in English. ['Zitat auf Deutsch.']{lang=de} + `dir` -: the base direction of the document, either `rtl` (right-to-left) +: the base script direction, either `rtl` (right-to-left) or `ltr` (left-to-right). For bidirectional documents, native pandoc `span`s and `div`s @@ -1436,22 +1431,19 @@ Language variables [BCP 47]: https://tools.ietf.org/html/bcp47 [Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics +[Language subtag lookup]: https://r12a.github.io/app-subtags/ -Variables for slides --------------------- - -Variables are available for [producing slide shows with pandoc], -including all [reveal.js configuration options]. +Variables for HTML slides +------------------------- -`titlegraphic` -: title graphic for Beamer documents +These affect HTML output when [producing slide shows with pandoc]. +All [reveal.js configuration options] are available as variables. -`logo` -: logo for Beamer documents +`revealjs-url` +: base URL for reveal.js documents (defaults to `reveal.js`) -`institute` -: author affiliations in Beamer. Can be a - list when there are multiple authors. +`s5-url` +: base URL for S5 documents (defaults to `s5/default`) `slidy-url` : base URL for Slidy documents (defaults to @@ -1460,80 +1452,120 @@ including all [reveal.js configuration options]. `slideous-url` : base URL for Slideous documents (defaults to `slideous`) -`s5-url` -: base URL for S5 documents (defaults to `s5/default`) +[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration -`revealjs-url` -: base URL for reveal.js documents (defaults to `reveal.js`) +Variables for Beamer slides +--------------------------- -`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` -: themes for LaTeX [`beamer`] documents +These variables change the appearance of PDF slides using [`beamer`]. -`themeoptions` -: options for LaTeX beamer themes (a list). +`aspectratio` +: slide aspect ratio (`43` for 4:3 [default], `169` for 16:9, + `1610` for 16:10, `149` for 14:9, `141` for 1.41:1, `54` for 5:4, + `32` for 3:2) + +`beamerarticle` +: produce an article from Beamer slides + +`beameroption` +: add extra beamer option with `\setbeameroption{}` + +`institute` +: author affiliations: can be a list when there are multiple authors + +`logo` +: logo image for slides `navigation` -: controls navigation symbols in `beamer` documents - (default is `empty` for no navigation symbols; other valid values - are `frame`, `vertical`, and `horizontal`). +: controls navigation symbols (default is `empty` for no navigation + symbols; other valid values are `frame`, `vertical`, and `horizontal`) `section-titles` -: enables on "title pages" for new sections in `beamer` - documents (default = true). +: enables "title pages" for new sections (default is true) -`beamerarticle` -: when true, the `beamerarticle` package is loaded (for - producing an article from beamer slides). +`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` +: beamer themes: -`aspectratio` -: aspect ratio of slides (for beamer only, `1610` for 16:10, `169` for 16:9, - `149` for 14:9, `141` for 1.41:1, `54` for 5:4, `43` for 4:3 which is the - default, and `32` for 3:2). +`themeoptions` +: options for LaTeX beamer themes (a list). -[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration +`titlegraphic` +: image for title slide Variables for LaTeX ------------------- -LaTeX variables are used when [creating a PDF]. - -`papersize` -: paper size, e.g. `letter`, `a4` - -`fontsize` -: font size for body text (e.g. `10pt`, `12pt`) +Pandoc uses these variables when [creating a PDF] with a LaTeX engine. -`documentclass` -: document class, e.g. [`article`], [`report`], [`book`], [`memoir`] +### Layout `classoption` -: option for document class, e.g. `oneside`; may be repeated - for multiple options +: option for document class, e.g. `oneside`; repeat for multiple options -`beameroption` -: In beamer, add extra beamer option with `\setbeameroption{}` +`documentclass` +: document class: usually one of the standard classes, [`article`], [`report`], + and [`book`]; the [KOMA-Script] equivalents, `scrartcl`, `scrreprt`, + and `scrbook`, which default to smaller margins; or [`memoir`] `geometry` : option for [`geometry`] package, e.g. `margin=1in`; - may be repeated for multiple options + repeat for multiple options -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: sets margins, if `geometry` is not used (otherwise `geometry` - overrides these) +`indent` +: uses document class settings for indentation (the default LaTeX template + otherwise removes indentation and adds space between paragraphs) `linestretch` : adjusts line spacing using the [`setspace`] package, e.g. `1.25`, `1.5` +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins if `geometry` is not used (otherwise `geometry` + overrides these) + +`pagestyle` +: control `\pagestyle{}`: the default article class + supports `plain` (default), `empty` (no running heads or page numbers), + and `headings` (section titles in running heads) + +`papersize` +: paper size, e.g. `letter`, `a4` + +`secnumdepth` +: numbering depth for sections (with `--number-sections` option + or `numbersections` variable) + +`subparagraph` +: disables default behavior of LaTeX template that redefines (sub)paragraphs + as sections, changing the appearance of nested headings in some classes + +### Fonts + +`fontenc` +: allows font encoding to be specified through `fontenc` package (with `pdflatex`); + default is `T1` (see [LaTeX font encodings guide]) + `fontfamily` : font package for use with `pdflatex`: [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. The default is [Latin Modern][`lm`]. `fontfamilyoptions` -: options for package used as `fontfamily`: e.g. `osf,sc` with - `fontfamily` set to [`mathpazo`] provides Palatino with old-style - figures and true small caps; may be repeated for multiple options +: options for package used as `fontfamily`; repeat for multiple options. + For example, to use the Libertine font with proportional lowercase + (old-style) figures through the [`libertinus`] package: + + --- + fontfamily: libertinus + fontfamilyoptions: + - osf + - p + ... + +`fontsize` +: font size for body text. The standard classes allow 10pt, 11pt, and 12pt. + To use another size, set `documentclass` to one of the [KOMA-Script] classes, + such as `scrartcl` or `scrbook`. `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` : font families for use with `xelatex` or @@ -1543,16 +1575,21 @@ LaTeX variables are used when [creating a PDF]. `mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` : options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` in `xelatex` and `lualatex`. Allow for any choices - available through [`fontspec`], such as the OpenType features - `Numbers=OldStyle,Numbers=Proportional`. May be repeated for multiple options. + available through [`fontspec`]; repeat for multiple options. For example, + to use the [TeX Gyre] version of Palatino with lowercase figures: -`fontenc` -: allows font encoding to be specified through `fontenc` package (with `pdflatex`); - default is `T1` (see guide to [LaTeX font encodings]) + --- + mainfont: TeX Gyre Pagella + mainfontoptions: + - Numbers=Lowercase + - Numbers=Proportional + ... `microtypeoptions` : options to pass to the microtype package +### Links + `colorlinks` : add color to link text; automatically enabled if any of `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set @@ -1566,16 +1603,13 @@ LaTeX variables are used when [creating a PDF]. `links-as-notes` : causes links to be printed as footnotes -`indent` -: uses document class settings for indentation (the default LaTeX template - otherwise removes indentation and adds space between paragraphs) +### Front matter -`subparagraph` -: disables default behavior of LaTeX template that redefines (sub)paragraphs - as sections, changing the appearance of nested headings in some classes +`lof`, `lot` +: include list of figures, list of tables `thanks` -: specifies contents of acknowledgments footnote after document title. +: contents of acknowledgments footnote after document title `toc` : include table of contents (can also be set using `--toc/--table-of-contents`) @@ -1583,14 +1617,12 @@ LaTeX variables are used when [creating a PDF]. `toc-depth` : level of section to include in table of contents -`secnumdepth` -: numbering depth for sections, if sections are numbered +### BibLaTeX Bibliographies -`lof`, `lot` -: include list of figures, list of tables +These variables function when using BibLaTeX for [citation rendering]. -`bibliography` -: bibliography to use for resolving references +`biblatexoptions` +: list of options for biblatex `biblio-style` : bibliography style, when used with `--natbib` and `--biblatex`. @@ -1598,46 +1630,45 @@ LaTeX variables are used when [creating a PDF]. `biblio-title` : bibliography title, when used with `--natbib` and `--biblatex`. -`biblatexoptions` -: list of options for biblatex. +`bibliography` +: bibliography to use for resolving references `natbiboptions` -: list of options for natbib. - -`pagestyle` -: An option for LaTeX's `\pagestyle{}`. The default article class - supports 'plain' (default), 'empty', and 'headings'; headings puts - section titles in the header. +: list of options for natbib +[KOMA-Script]: https://ctan.org/pkg/koma-script +[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ +[LaTeX font encodings guide]: https://ctan.org/pkg/encguide +[TeX Gyre]: http://www.gust.org.pl/projects/e-foundry/tex-gyre [`article`]: https://ctan.org/pkg/article -[`report`]: https://ctan.org/pkg/report [`book`]: https://ctan.org/pkg/book -[KOMA-Script]: https://ctan.org/pkg/koma-script +[`libertinus`]: https://ctan.org/pkg/libertinus [`memoir`]: https://ctan.org/pkg/memoir -[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ -[`mathpazo`]: https://ctan.org/pkg/mathpazo -[LaTeX font encodings]: https://ctan.org/pkg/encguide +[`report`]: https://ctan.org/pkg/report Variables for ConTeXt --------------------- -`papersize` -: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); - may be repeated for multiple options - -`layout` -: options for page margins and text arrangement (see [ConTeXt Layout]); - may be repeated for multiple options - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: sets margins, if `layout` is not used (otherwise `layout` - overrides these) +Pandoc uses these variables when [creating a PDF] with ConTeXt. `fontsize` : font size for body text (e.g. `10pt`, `12pt`) -`mainfont`, `sansfont`, `monofont`, `mathfont` -: font families: take the name of any system font (see [ConTeXt Font Switching]) +`headertext`, `footertext` +: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); + repeat up to four times for different placement + +`indenting` +: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); + repeat for multiple options + +`interlinespace` +: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); + repeat for multiple options + +`layout` +: options for page margins and text arrangement (see [ConTeXt Layout]); + repeat for multiple options `linkcolor`, `contrastcolor` : color for links outside and inside a page, e.g. `red`, `blue` (see [ConTeXt Color]) @@ -1645,30 +1676,23 @@ Variables for ConTeXt `linkstyle` : typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, `type`, `cap`, `small` -`indenting` -: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); - may be repeated for multiple options - -`whitespace` -: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) +`lof`, `lot` +: include list of figures, list of tables -`interlinespace` -: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); - may be repeated for multiple options +`mainfont`, `sansfont`, `monofont`, `mathfont` +: font families: take the name of any system font (see [ConTeXt Font Switching]) -`headertext`, `footertext` -: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); - may be repeated up to four times for different placement +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `layout` is not used (otherwise `layout` + overrides these) `pagenumbering` : page number style and location (using [`setuppagenumbering`]); - may be repeated for multiple options + repeat for multiple options -`toc` -: include table of contents (can also be set using `--toc/--table-of-contents`) - -`lof`, `lot` -: include list of figures, list of tables +`papersize` +: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); + repeat for multiple options `pdfa` : adds to the preamble the setup necessary to generate PDF/A-1b:2005. @@ -1678,6 +1702,12 @@ Variables for ConTeXt from [ConTeXt ICC Profiles]. See also [ConTeXt PDFA] for more details. +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`whitespace` +: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) + [ConTeXt Paper Setup]: https://wiki.contextgarden.net/PaperSetup [ConTeXt Layout]: https://wiki.contextgarden.net/Layout [ConTeXt Font Switching]: https://wiki.contextgarden.net/Font_Switching @@ -1690,40 +1720,107 @@ Variables for ConTeXt [`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace [`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering -Variables for man pages ------------------------ +Variables for `wkhtmltopdf` +--------------------------- -`section` -: section number in man pages +Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`]. +The `--css` option also affects the output. -`header` -: header in man pages +`footer-html`, `header-html` +: add information to the header and footer -`footer` -: footer in man pages +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: set the page margins + +`papersize` +: sets the PDF paper size + +Variables for man pages +----------------------- `adjusting` : adjusts text to left (`l`), right (`r`), center (`c`), or both (`b`) margins +`footer` +: footer in man pages + +`header` +: header in man pages + `hyphenate` : if `true` (the default), hyphenation will be used +`section` +: section number in man pages + Variables for ms ---------------- -`pointsize` -: point size (e.g. `10p`) - -`lineheight` -: line height (e.g. `12p`) - `fontfamily` : font family (e.g. `T` or `P`) `indent` : paragraph indent (e.g. `2m`) +`lineheight` +: line height (e.g. `12p`) + +`pointsize` +: point size (e.g. `10p`) + +Structural variables +-------------------- + +Pandoc sets these variables automatically in response to [options] or +document contents; users can also modify them. These vary depending +on the output format, and include the following: + +`body` +: body of document + +`header-includes` +: contents specified by `-H/--include-in-header` (may have multiple + values) + +`include-before` +: contents specified by `-B/--include-before-body` (may have + multiple values) + +`include-after` +: contents specified by `-A/--include-after-body` (may have + multiple values) + +`meta-json` +: JSON representation of all of the document's metadata. Field + values are transformed to the selected output format. + +`numbersections` +: non-null value if `-N/--number-sections` was specified + +`sourcefile`, `outputfile` +: source and destination filenames, as given on the command line. + `sourcefile` can also be a list if input comes from multiple files, or empty + if input is from stdin. You can use the following snippet in your template + to distinguish them: + + $if(sourcefile)$ + $for(sourcefile)$ + $sourcefile$ + $endfor$ + $else$ + (stdin) + $endif$ + + Similarly, `outputfile` can be `-` if output goes to the terminal. + +`toc` +: non-null value if `--toc/--table-of-contents` was specified + +`toc-title` +: title of table of contents (works only with EPUB, + opendocument, odt, docx, pptx, beamer, LaTeX) + Using variables in templates ---------------------------- @@ -4352,7 +4449,7 @@ For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the assumed to be available at the relative path `s5/default` (for S5), `slideous` (for Slideous), `reveal.js` (for reveal.js), or at the Slidy website at `w3.org` (for Slidy). (These paths can be changed by setting the `slidy-url`, -`slideous-url`, `revealjs-url`, or `s5-url` variables; see [Variables for slides], +`slideous-url`, `revealjs-url`, or `s5-url` variables; see [Variables for HTML slides], above.) For DZSlides, the (relatively short) JavaScript and CSS are included in the file by default. @@ -5059,7 +5156,7 @@ application, here are some things to keep in mind: Authors ======= -Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu). Released +Copyright 2006--2019 John MacFarlane (jgm@berkeley.edu). Released under the [GPL], version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) For a full list of contributors, see the file |