diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/pandoc.1 | 307 |
1 files changed, 229 insertions, 78 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1 index 0126fc6de..6d000f775 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,5 +1,5 @@ .\"t -.TH PANDOC 1 "November 12, 2015" "pandoc 1.15.2.1" +.TH PANDOC 1 "November 12, 2015" "pandoc 1.16" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -20,8 +20,8 @@ Texinfo, MediaWiki markup, DokuWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2, Textile, groff man pages, Emacs Org mode, AsciiDoc, InDesign ICML, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. -It can also produce PDF output on systems where LaTeX or ConTeXt is -installed. +It can also produce PDF output on systems where LaTeX, ConTeXt, or +\f[C]wkhtmltopdf\f[] is installed. .PP Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, fenced code blocks, @@ -174,40 +174,34 @@ Production of a PDF requires that a LaTeX engine be installed (see packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[], \f[C]lm\f[], \f[C]ifxetex\f[], \f[C]ifluatex\f[], \f[C]eurosym\f[], \f[C]listings\f[] (if the \f[C]\-\-listings\f[] option is used), -\f[C]fancyvrb\f[], \f[C]longtable\f[], \f[C]booktabs\f[], \f[C]url\f[], +\f[C]fancyvrb\f[], \f[C]longtable\f[], \f[C]booktabs\f[], \f[C]graphicx\f[] and \f[C]grffile\f[] (if the document contains -images), \f[C]color\f[], \f[C]hyperref\f[], \f[C]ulem\f[], -\f[C]geometry\f[] (with the \f[C]geometry\f[] variable set), -\f[C]setspace\f[] (with \f[C]linestretch\f[]), and \f[C]babel\f[] (with -\f[C]lang\f[]). +images), \f[C]hyperref\f[], \f[C]ulem\f[], \f[C]geometry\f[] (with the +\f[C]geometry\f[] variable set), \f[C]setspace\f[] (with +\f[C]linestretch\f[]), and \f[C]babel\f[] (with \f[C]lang\f[]). The use of \f[C]xelatex\f[] or \f[C]lualatex\f[] as the LaTeX engine requires \f[C]fontspec\f[]; \f[C]xelatex\f[] uses \f[C]mathspec\f[], \f[C]polyglossia\f[] (with \f[C]lang\f[]), \f[C]xecjk\f[], and \f[C]bidi\f[] (with the \f[C]dir\f[] variable set). The \f[C]upquote\f[] and \f[C]microtype\f[] packages are used if available, and \f[C]csquotes\f[] will be used for smart punctuation if -added to the template. +added to the template or included in any header file. The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and \f[C]biber\f[] packages can optionally be used for citation rendering. These are included with all recent versions of TeX Live. .PP -Alternatively, pandoc can use ConTeXt to create a PDF. +Alternatively, pandoc can use ConTeXt or \f[C]wkhtmltopdf\f[] to create +a PDF. To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as -before, but add \f[C]\-t\ context\f[] to the command line. -.PP -PDF output can be controlled using variables for LaTeX or variables for -ConTeXt. -.SS \f[C]hsmarkdown\f[] -.PP -A user who wants a drop\-in replacement for \f[C]Markdown.pl\f[] may -create a symbolic link to the \f[C]pandoc\f[] executable called -\f[C]hsmarkdown\f[]. -When invoked under the name \f[C]hsmarkdown\f[], \f[C]pandoc\f[] will -behave as if invoked with -\f[C]\-f\ markdown_strict\ \-\-email\-obfuscation=references\f[], and -all command\-line options will be treated as regular arguments. -This approach does not work under Cygwin, due to problems with its -simulation of symbolic links. +before, but add \f[C]\-t\ context\f[] or \f[C]\-t\ html5\f[] to the +command line. +.PP +PDF output can be controlled using variables for LaTeX (if LaTeX is +used) and variables for ConTeXt (if ConTeXt is used). +If \f[C]wkhtmltopdf\f[] is used, then the variables +\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], +\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output, +as will \f[C]\-\-css\f[]. .SH OPTIONS .SS General options .TP @@ -373,7 +367,8 @@ en\-dashes, and \f[C]\&...\f[] to ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as "Mr." (Note: This option is selected automatically when the output format is \f[C]latex\f[] or \f[C]context\f[], unless -\f[C]\-\-no\-tex\-ligatures\f[] is used.) +\f[C]\-\-no\-tex\-ligatures\f[] is used. +It has no effect for \f[C]latex\f[] input.) .RS .RE .TP @@ -552,14 +547,36 @@ Files in the user data directory are ignored. .RS .RE .TP +.B \f[C]\-\-dpi\f[]=\f[I]NUMBER\f[] +Specify the dpi (dots per inch) value for conversion from pixels to +inch/centimeters and vice versa. +The default is 96dpi. +Technically, the correct term would be ppi (pixels per inch). +.RS +.RE +.TP +.B \f[C]\-\-wrap=[auto|none|preserve]\f[] +Determine how text is wrapped in the output (the source code, not the +rendered version). +With \f[C]auto\f[] (the default), pandoc will attempt to wrap lines to +the column width specified by \f[C]\-\-columns\f[] (default 80). +With \f[C]none\f[], pandoc will not wrap lines at all. +With \f[C]preserve\f[], pandoc will attempt to preserve the wrapping +from the source document (that is, where there are nonsemantic newlines +in the source, there will be nonsemantic newlines in the output as +well). +.RS +.RE +.TP .B \f[C]\-\-no\-wrap\f[] -Disable text wrapping in output. -By default, text is wrapped appropriately for the output format. +Deprecated synonym for \f[C]\-\-wrap=none\f[]. .RS .RE .TP .B \f[C]\-\-columns=\f[]\f[I]NUMBER\f[] Specify length of lines in characters (for text wrapping). +This affects only the generated source code, not the layout on the +rendered page. .RS .RE .TP @@ -647,19 +664,11 @@ Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source file is remote). -\f[C]\-\-self\-contained\f[] does not work with \f[C]\-\-mathjax\f[]. -.RS -.RE -.TP -.B \f[C]\-\-offline\f[] -Deprecated synonym for \f[C]\-\-self\-contained\f[]. -.RS -.RE -.TP -.B \f[C]\-5\f[], \f[C]\-\-html5\f[] -Produce HTML5 instead of HTML4. -This option has no effect for writers other than \f[C]html\f[]. -(\f[I]Deprecated:\f[] Use the \f[C]html5\f[] output format instead.) +Limitation: resources that are loaded dynamically through JavaScript +cannot be incorporated; as a result, \f[C]\-\-self\-contained\f[] does +not work with \f[C]\-\-mathjax\f[], and some advanced features (e.g. +zoom or speaker notes) may not work in an offline "self\-contained" +\f[C]reveal.js\f[] slide show. .RS .RE .TP @@ -722,11 +731,15 @@ Implies \f[C]\-\-number\-sections\f[]. .RE .TP .B \f[C]\-\-no\-tex\-ligatures\f[] -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 -\f[C]xelatex\f[] and \f[C]lualatex\f[]. +Do not use the TeX ligatures for quotation marks, apostrophes, and +dashes (\f[C]`...\[aq]\f[], \f[C]``..\[aq]\[aq]\f[], \f[C]\-\-\f[], +\f[C]\-\-\-\f[]) when writing or reading LaTeX or ConTeXt. +In reading LaTeX, parse the characters \f[C]`\f[], \f[C]\[aq]\f[], and +\f[C]\-\f[] literally, rather than parsing ligatures for quotation marks +and dashes. +In writing LaTeX or ConTeXt, print unicode quotation mark and dash +characters literally, rather than converting them to the standard ASCII +TeX ligatures. Note: normally \f[C]\-\-smart\f[] is selected automatically for LaTeX and ConTeXt output, but it must be specified explicitly if \f[C]\-\-no\-tex\-ligatures\f[] is selected. @@ -1171,7 +1184,10 @@ author: .RE .TP .B \f[C]subtitle\f[] -document subtitle; also used as subject in PDF metadata +document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word +docx; renders in LaTeX only when using a document class that supports +\f[C]\\subtitle\f[], such as \f[C]beamer\f[] or the KOMA\-Script series +(\f[C]scrartcl\f[], \f[C]scrreprt\f[], \f[C]scrbook\f[]). .RS .RE .TP @@ -1219,6 +1235,11 @@ multiple values) body of document .RS .RE +.TP +.B \f[C]meta\-json\f[] +JSON representation of all of the document\[aq]s metadata +.RS +.RE .SS Language variables .TP .B \f[C]lang\f[] @@ -1295,10 +1316,29 @@ base URL for reveal.js documents (defaults to \f[C]reveal.js\f[]) themes for LaTeX \f[C]beamer\f[] documents .RS .RE +.TP +.B \f[C]navigation\f[] +controls navigation symbols in \f[C]beamer\f[] documents (default is +\f[C]empty\f[] for no navigation symbols; other valid values are +\f[C]frame\f[], \f[C]vertical\f[], and \f[C]horizontal\f[]). +.RS +.RE +.TP +.B \f[C]section\-titles\f[] +enables on "title pages" for new sections in \f[C]beamer\f[] documents +(default = true). +.RS +.RE .SS Variables for LaTeX .PP LaTeX variables are used when creating a PDF. .TP +.B \f[C]papersize\f[] +paper size, e.g. +\f[C]letter\f[], \f[C]A4\f[] +.RS +.RE +.TP .B \f[C]fontsize\f[] font size for body text (e.g. \f[C]10pt\f[], \f[C]12pt\f[]) @@ -1323,6 +1363,12 @@ option for \f[C]geometry\f[] package, e.g. .RS .RE .TP +.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[] +sets margins, if \f[C]geometry\f[] is not used (otherwise +\f[C]geometry\f[] overrides these) +.RS +.RE +.TP .B \f[C]linestretch\f[] adjusts line spacing using the \f[C]setspace\f[] package, e.g. \f[C]1.25\f[], \f[C]1.5\f[] @@ -1369,18 +1415,16 @@ font encodings) .RS .RE .TP -.B \f[C]linkcolor\f[], \f[C]toccolor\f[], \f[C]urlcolor\f[], \f[C]citecolor\f[] -color for internal links, links in table of contents, external links, -and citation links, using options available through \f[C]color\f[] -package, e.g. -\f[C]red\f[], \f[C]green\f[], \f[C]magenta\f[], \f[C]cyan\f[], -\f[C]blue\f[], \f[C]black\f[] +.B \f[C]colorlinks\f[] +add color to link text; automatically enabled if any of +\f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], or +\f[C]toccolor\f[] are set .RS .RE .TP -.B \f[C]hidelinks\f[] -enables \f[C]hidelinks\f[] option for \f[C]hyperref\f[], disabling link -color +.B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[] +color for internal links, citation links, external links, and links in +table of contents: uses any of the predefined LaTeX colors .RS .RE .TP @@ -1402,6 +1446,11 @@ in some classes .RS .RE .TP +.B \f[C]thanks\f[] +specifies contents of acknowledgments footnote after document title. +.RS +.RE +.TP .B \f[C]toc\f[] include table of contents (can also be set using \f[C]\-\-toc/\-\-table\-of\-contents\f[]) @@ -1424,7 +1473,13 @@ bibliography to use for resolving references .RE .TP .B \f[C]biblio\-style\f[] -bibliography style, when used with \f[C]\-\-natbib\f[] +bibliography style, when used with \f[C]\-\-natbib\f[] and +\f[C]\-\-biblatex\f[]. +.RS +.RE +.TP +.B \f[C]biblatexoptions\f[] +list of options for biblatex. .RS .RE .SS Variables for ConTeXt @@ -1442,6 +1497,12 @@ be repeated for multiple options .RS .RE .TP +.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[] +sets margins, if \f[C]layout\f[] is not used (otherwise \f[C]layout\f[] +overrides these) +.RS +.RE +.TP .B \f[C]fontsize\f[] font size for body text (e.g. \f[C]10pt\f[], \f[C]12pt\f[]) @@ -1454,12 +1515,19 @@ Switching) .RS .RE .TP -.B \f[C]linkcolor\f[] -color for links, e.g. +.B \f[C]linkcolor\f[], \f[C]contrastcolor\f[] +color for links outside and inside a page, e.g. \f[C]red\f[], \f[C]blue\f[] (see ConTeXt Color) .RS .RE .TP +.B \f[C]linkstyle\f[] +typeface style for links, e.g. +\f[C]normal\f[], \f[C]bold\f[], \f[C]slanted\f[], \f[C]boldslanted\f[], +\f[C]type\f[], \f[C]cap\f[], \f[C]small\f[] +.RS +.RE +.TP .B \f[C]indenting\f[] controls indentation of paragraphs, e.g. \f[C]yes,small,next\f[] (see ConTeXt Indentation); may be repeated for @@ -2742,10 +2810,10 @@ orange|3.09 .PP The cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. -Note also that in LaTeX/PDF output, the cells produced by pipe tables -will not wrap, since there is no information available about relative -widths. -If you want content to wrap within cells, use multiline or grid tables. +If a pipe table contains a row whose printable content is wider than the +column width (see \f[C]\-\-columns\f[]), then the cell contents will +wrap, with the relative cell widths determined by the widths of the +separator lines. .PP Note: pandoc also recognizes pipe tables of the following form, as can be produced by Emacs\[aq] orgtbl\-mode: @@ -3028,9 +3096,9 @@ quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to en\-dashes, and Nonbreaking spaces are inserted after certain abbreviations, such as "Mr." .PP -Note: if your LaTeX template calls for the \f[C]csquotes\f[] package, -pandoc will detect this automatically and use \f[C]\\enquote{...}\f[] -for quoted text. +Note: if your LaTeX template or any included header file call for the +\f[C]csquotes\f[] package, pandoc will detect this automatically and use +\f[C]\\enquote{...}\f[] for quoted text. .SS Inline formatting .SS Emphasis .PP @@ -3410,8 +3478,14 @@ For output formats other than LaTeX, pandoc will parse LaTeX the resulting macros to all LaTeX math. So, for example, the following will work in all output formats, not just LaTeX: -.PP -⟨\f[I]a\f[], \f[I]b\f[], \f[I]c\f[]⟩ +.IP +.nf +\f[C] +\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle} + +$\\tuple{a,\ b,\ c}$ +\f[] +.fi .PP In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be passed unchanged to the output. @@ -3608,6 +3682,61 @@ One way to do this is to insert a nonbreaking space after the image: ![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\ \f[] .fi +.SS Extension: \f[C]link_attributes\f[] +.PP +Attributes can be set on links and images: +.IP +.nf +\f[C] +An\ inline\ {#id\ .class\ width=30\ height=20px} +and\ a\ reference\ ![image][ref]\ with\ attributes. + +[ref]:\ foo.jpg\ "optional\ title"\ {#id\ .class\ key=val\ key2="val\ 2"} +\f[] +.fi +.PP +(This syntax is compatible with PHP Markdown Extra when only +\f[C]#id\f[] and \f[C]\&.class\f[] are used.) +.PP +For HTML and EPUB, all attributes except \f[C]width\f[] and +\f[C]height\f[] (but including \f[C]srcset\f[] and \f[C]sizes\f[]) are +passed through as is. +The other writers ignore attributes that are not supported by their +output format. +.PP +The \f[C]width\f[] and \f[C]height\f[] attributes on images are treated +specially. +When used without a unit, the unit is assumed to be pixels. +However, any of the following unit identifiers can be used: \f[C]px\f[], +\f[C]cm\f[], \f[C]mm\f[], \f[C]in\f[], \f[C]inch\f[] and \f[C]%\f[]. +There must not be any spaces between the number and the unit. +For example: +.IP +.nf +\f[C] +{\ width=50%\ } +\f[] +.fi +.IP \[bu] 2 +Dimensions are converted to inches for output in page\-based formats +like LaTeX. +Dimensions are converted to pixels for output in HTML\-like formats. +Use the \f[C]\-\-dpi\f[] option to specify the number of pixels per +inch. +The default is 96dpi. +.IP \[bu] 2 +The \f[C]%\f[] unit is generally relative to some available space. +For example the above example will render to +\f[C]<img\ href="file.jpg"\ style="width:\ 50%;"\ />\f[] (HTML), +\f[C]\\includegraphics[width=0.5\\textwidth]{file.jpg}\f[] (LaTeX), or +\f[C]\\externalfigure[file.jpg][width=0.5\\textwidth]\f[] (ConTeXt). +.IP \[bu] 2 +Some output formats have a notion of a class (ConTeXt) or a unique +identifier (LaTeX \f[C]\\caption\f[]), or both (HTML). +.IP \[bu] 2 +When no \f[C]width\f[] or \f[C]height\f[] attributes are specified, the +fallback is to look at the image resolution and the dpi metadata +embedded in the image file. .SS Footnotes .SS Extension: \f[C]footnotes\f[] .PP @@ -3790,9 +3919,10 @@ prevent a phrase from being capitalized as title case \f[C]pandoc\-citeproc\ \-j\f[] and \f[C]\-y\f[] interconvert the CSL JSON and CSL YAML formats as far as possible. .PP -As an alternative to specifying a bibliography file, you can include the -citation data directly in the \f[C]references\f[] field of the -document\[aq]s YAML metadata. +As an alternative to specifying a bibliography file using +\f[C]\-\-bibliography\f[] or the YAML metadata field +\f[C]bibliography\f[], you can include the citation data directly in the +\f[C]references\f[] field of the document\[aq]s YAML metadata. The field should contain an array of YAML\-encoded references, for example: .IP @@ -3838,6 +3968,9 @@ Style author\-date format. The CSL project provides further information on finding and editing styles. .PP +To make your citations hyperlinks to the corresponding bibliography +entries, add \f[C]link\-citations:\ true\f[] to your YAML metadata. +.PP Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of \[aq]\@\[aq] + the citation identifier from the database, and may optionally have a prefix, a @@ -3938,6 +4071,8 @@ In order to do so, specify bibliography files as outlined above, and add invocation. Bear in mind that bibliography files have to be in respective format (either BibTeX or BibLaTeX). +.PP +For more information, see the pandoc\-citeproc man page. .SS Non\-pandoc extensions .PP The following Markdown syntax extensions are not enabled by default in @@ -3960,6 +4095,13 @@ treated as spaces or as hard line breaks. This option is intended for use with East Asian languages where spaces are not used between words, but text is divided into lines for readability. +.SS Extension: \f[C]east_asian_line_breaks\f[] +.PP +Causes newlines within a paragraph to be ignored, rather than being +treated as spaces or as hard line breaks, when they occur between two +East Asian wide characters. +This is a better choice than \f[C]ignore_line_breaks\f[] for texts that +include a mix of East Asian wide characters and other characters. .SS Extension: \f[C]emoji\f[] .PP Parses textual emojis like \f[C]:smile:\f[] as Unicode emoticons. @@ -4023,12 +4165,21 @@ Causes the identifiers produced by \f[C]auto_identifiers\f[] to be pure ASCII. Accents are stripped off of accented latin letters, and non\-latin letters are omitted. -.SS Extension: \f[C]link_attributes\f[] +.SS Extension: \f[C]mmd_link_attributes\f[] .PP Parses multimarkdown style key\-value attributes on link and image references. -Note that pandoc\[aq]s internal document model provides nowhere to put -these, so they are presently just ignored. +This extension should not be confused with the \f[C]link_attributes\f[] +extension. +.IP +.nf +\f[C] +This\ is\ a\ reference\ ![image][ref]\ with\ multimarkdown\ attributes. + +[ref]:\ http://path.to/image\ "Image\ title"\ width=20px\ height=30px +\ \ \ \ \ \ \ id=myId\ class="myClass1\ myClass2" +\f[] +.fi .SS Extension: \f[C]mmd_header_identifiers\f[] .PP Parses multimarkdown style header identifiers (in square brackets, after @@ -4057,8 +4208,8 @@ variants are supported: \f[C]footnotes\f[], \f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]markdown_attribute\f[], \f[C]fenced_code_blocks\f[], \f[C]definition_lists\f[], \f[C]intraword_underscores\f[], -\f[C]header_attributes\f[], \f[C]abbreviations\f[], -\f[C]shortcut_reference_links\f[]. +\f[C]header_attributes\f[], \f[C]link_attributes\f[], +\f[C]abbreviations\f[], \f[C]shortcut_reference_links\f[]. .RS .RE .TP @@ -4075,7 +4226,7 @@ variants are supported: .TP .B \f[C]markdown_mmd\f[] (MultiMarkdown) \f[C]pipe_tables\f[] \f[C]raw_html\f[], \f[C]markdown_attribute\f[], -\f[C]link_attributes\f[], \f[C]raw_tex\f[], +\f[C]mmd_link_attributes\f[], \f[C]raw_tex\f[], \f[C]tex_math_double_backslash\f[], \f[C]intraword_underscores\f[], \f[C]mmd_title_block\f[], \f[C]footnotes\f[], \f[C]definition_lists\f[], \f[C]all_symbols_escapable\f[], \f[C]implicit_header_references\f[], @@ -4629,7 +4780,7 @@ Bogner, Kelsey Hightower, Konstantin Zudov, Lars\-Dominik Braun, Luke Plant, Mark Szepieniec, Mark Wright, Masayoshi Takahashi, Matej Kollar, Mathias Schenner, Matthew Pickering, Matthias C. M. -Troffaes, Max Bolingbroke, Max Rydahl Andersen, mb21, Merijn +Troffaes, Mauro Bieg, Max Bolingbroke, Max Rydahl Andersen, Merijn Verstraaten, Michael Snoyman, Michael Thompson, MinRK, Nathan Gass, Neil Mayhew, Nick Bart, Nicolas Kaiser, Nikolay Yakimov, nkalvi, Paulo Tanimoto, Paul Rivier, Peter Wang, Philippe Ombredanne, Phillip Alday, |