diff options
Diffstat (limited to 'man/pandoc.1')
-rw-r--r-- | man/pandoc.1 | 375 |
1 files changed, 199 insertions, 176 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1 index bd6a85002..ee33b09ba 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,5 +1,5 @@ .\"t -.TH PANDOC 1 "December 27, 2017" "pandoc 2.1" +.TH PANDOC 1 "January 18, 2018" "pandoc 2.1.1" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -9,38 +9,39 @@ pandoc - general markup converter .PP Pandoc is a Haskell library for converting from one markup format to another, and a command\-line tool that uses this library. -It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored -Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText, -HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup, Creole -1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, Muse, -txt2tags, Vimwiki, EPUB, ODT, and Word docx; and it can write plain -text, Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored -Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX -(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook, -JATS, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, -DokuWiki markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3), -FictionBook2, Textile, groff man, groff ms, Emacs Org mode, AsciiDoc, -InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and Slidy, -Slideous, DZSlides, reveal.js or S5 HTML slide shows. +.PP +Pandoc can read Markdown, CommonMark, PHP Markdown Extra, +GitHub\-Flavored Markdown, MultiMarkdown, and (subsets of) Textile, +reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki +markup, Creole 1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, +Muse, txt2tags, Vimwiki, EPUB, ODT, and Word docx. +.PP +Pandoc can write plain text, Markdown, CommonMark, PHP Markdown Extra, +GitHub\-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML, +HTML5, LaTeX (including \f[C]beamer\f[] slide shows), ConTeXt, RTF, +OPML, DocBook, JATS, OpenDocument, ODT, Word docx, GNU Texinfo, +MediaWiki markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB +(v2 or v3), FictionBook2, Textile, groff man, groff ms, Emacs Org mode, +AsciiDoc, InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and +Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. It can also produce PDF output on systems where LaTeX, ConTeXt, \f[C]pdfroff\f[], \f[C]wkhtmltopdf\f[], \f[C]prince\f[], or \f[C]weasyprint\f[] is installed. .PP -Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes, -tables, flexible ordered lists, definition lists, fenced code blocks, -superscripts and subscripts, strikeout, metadata blocks, automatic -tables of contents, embedded LaTeX math, citations, and Markdown inside -HTML block elements. -(These enhancements, described further under Pandoc\[aq]s Markdown, can -be disabled using the \f[C]markdown_strict\f[] input or output format.) -.PP -In contrast to most existing tools for converting Markdown to HTML, -which use regex substitutions, pandoc has a modular design: it consists -of a set of readers, which parse text in a given format and produce a -native representation of the document, and a set of writers, which -convert this native representation into a target format. +Pandoc\[aq]s enhanced version of Markdown includes syntax for tables, +definition lists, metadata blocks, \f[C]Div\f[] blocks, footnotes and +citations, embedded LaTeX (including math), Markdown inside HTML block +elements, and much more. +These enhancements, described further under Pandoc\[aq]s Markdown, can +be disabled using the \f[C]markdown_strict\f[] format. +.PP +Pandoc has a modular design: it consists of a set of readers, which +parse text in a given format and produce a native representation of the +document (like an \f[I]abstract syntax tree\f[] or AST), and a set of +writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer. +Users can also run custom pandoc filters to modify the intermediate AST. .PP Because pandoc\[aq]s intermediate representation of a document is less expressive than many of the formats it converts between, one should not @@ -54,14 +55,9 @@ perfect, conversions from formats more expressive than pandoc\[aq]s Markdown can be expected to be lossy. .SS Using \f[C]pandoc\f[] .PP -If no \f[I]input\-file\f[] is specified, input is read from +If no \f[I]input\-files\f[] are specified, input is read from \f[I]stdin\f[]. -Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line -between each) and used as input. -Output goes to \f[I]stdout\f[] by default (though output to the terminal -is disabled for the \f[C]odt\f[], \f[C]docx\f[], \f[C]epub2\f[], and -\f[C]epub3\f[] output formats, unless it is forced using -\f[C]\-o\ \-\f[]). +Output goes to \f[I]stdout\f[] by default. For output to a file, use the \f[C]\-o\f[] option: .IP .nf @@ -70,10 +66,10 @@ pandoc\ \-o\ output.html\ input.txt \f[] .fi .PP -By default, pandoc produces a document fragment, not a standalone -document with a proper header and footer. -To produce a standalone document, use the \f[C]\-s\f[] or -\f[C]\-\-standalone\f[] flag: +By default, pandoc produces a document fragment. +To produce a standalone document (e.g. +a valid HTML file including \f[C]<head>\f[] and \f[C]<body>\f[]), use +the \f[C]\-s\f[] or \f[C]\-\-standalone\f[] flag: .IP .nf \f[C] @@ -82,37 +78,17 @@ pandoc\ \-s\ \-o\ output.html\ input.txt .fi .PP For more information on how standalone documents are produced, see -Templates, below. -.PP -Instead of a file, an absolute URI may be given. -In this case pandoc will fetch the content using HTTP: -.IP -.nf -\f[C] -pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org -\f[] -.fi -.PP -It is possible to supply a custom User\-Agent string or other header -when requesting a document from a URL: -.IP -.nf -\f[C] -pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\ -\ \ http://www.fsf.org -\f[] -.fi +Templates below. .PP If multiple input files are given, \f[C]pandoc\f[] will concatenate them all (with blank lines between them) before parsing. -This feature is disabled for binary input formats such as \f[C]EPUB\f[], -\f[C]odt\f[], and \f[C]docx\f[]. +(Use \f[C]\-\-file\-scope\f[] to parse files individually.) +.SS Specifying formats .PP The format of the input and output can be specified explicitly using command\-line options. -The input format can be specified using the \f[C]\-r/\-\-read\f[] or -\f[C]\-f/\-\-from\f[] options, the output format using the -\f[C]\-w/\-\-write\f[] or \f[C]\-t/\-\-to\f[] options. +The input format can be specified using the \f[C]\-f/\-\-from\f[] +option, the output format using the \f[C]\-t/\-\-to\f[] option. Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could type: .IP @@ -130,17 +106,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ hello.html \f[] .fi .PP -Supported output formats are listed below under the \f[C]\-t/\-\-to\f[] -option. -Supported input formats are listed below under the \f[C]\-f/\-\-from\f[] -option. -Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and -\f[C]html\f[] readers are not complete; there are some constructs that -they do not parse. +Supported input and output formats are listed below under Options (see +\f[C]\-f\f[] for input formats and \f[C]\-t\f[] for output formats). +You can also use \f[C]pandoc\ \-\-list\-input\-formats\f[] and +\f[C]pandoc\ \-\-list\-output\-formats\f[] to print lists of supported +formats. .PP If the input or output format is not specified explicitly, \f[C]pandoc\f[] will attempt to guess it from the extensions of the -input and output filenames. +filenames. Thus, for example, .IP .nf @@ -155,7 +129,8 @@ or if the output file\[aq]s extension is unknown, the output format will default to HTML. If no input file is specified (so that input comes from \f[I]stdin\f[]), or if the input files\[aq] extensions are unknown, the input format will -be assumed to be Markdown unless explicitly specified. +be assumed to be Markdown. +.SS Character encoding .PP Pandoc uses the UTF\-8 character encoding for both input and output. If your local character encoding is not UTF\-8, you should pipe input @@ -174,8 +149,7 @@ the \f[C]\-s/\-\-standalone\f[] option. .SS Creating a PDF .PP To produce a PDF, specify an output file with a \f[C]\&.pdf\f[] -extension. -By default, pandoc will use LaTeX to create the PDF: +extension: .IP .nf \f[C] @@ -183,10 +157,34 @@ pandoc\ test.txt\ \-o\ test.pdf \f[] .fi .PP -Production of a PDF requires that a LaTeX engine be installed (see -\f[C]\-\-pdf\-engine\f[], below), and assumes that the following LaTeX -packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[], -\f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[], +By default, pandoc will use LaTeX to create the PDF, which requires that +a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[] below). +.PP +Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the +following HTML/CSS\-to\-PDF\-engines, to create a PDF: +\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[]. +To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as +before, but add the \f[C]\-\-pdf\-engine\f[] option or +\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the +command line (\f[C]\-t\ html\f[] defaults to +\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]). +.PP +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, \f[C]\-\-css\f[] affects the +output. +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. +.PP +To debug the PDF creation, it can be useful to look at the intermediate +representation: instead of \f[C]\-o\ test.pdf\f[], use for example +\f[C]\-s\ \-o\ test.tex\f[] to output the generated LaTeX. +You can then test it with \f[C]pdflatex\ test.tex\f[]. +.PP +When using LaTeX, the following packages need to be available (they are +included with all recent versions of TeX Live): \f[C]amsfonts\f[], +\f[C]amsmath\f[], \f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[], \f[C]ifluatex\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]graphicx\f[] and \f[C]grffile\f[] (if the @@ -205,24 +203,26 @@ available, and \f[C]csquotes\f[] will be used for typography if 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. +.SS Reading from the Web .PP -Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the -following HTML/CSS\-to\-PDF\-engines, to create a PDF: -\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[]. -To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as -before, but add the \f[C]\-\-pdf\-engine\f[] option or -\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the -command line (\f[C]\-t\ html\f[] defaults to -\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]). +Instead of an input file, an absolute URI may be given. +In this case pandoc will fetch the content using HTTP: +.IP +.nf +\f[C] +pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org +\f[] +.fi .PP -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, \f[C]\-\-css\f[] affects the -output. -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. +It is possible to supply a custom User\-Agent string or other header +when requesting a document from a URL: +.IP +.nf +\f[C] +pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\ +\ \ http://www.fsf.org +\f[] +.fi .SH OPTIONS .SS General options .TP @@ -283,9 +283,8 @@ show) or the path of a custom lua writer (see Custom writers, below). (\f[C]markdown_github\f[] provides deprecated and less accurate support for Github\-Flavored Markdown; please use \f[C]gfm\f[] instead, unless you use extensions that do not work with \f[C]gfm\f[].) Note that -\f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will not be -directed to \f[I]stdout\f[]; an output filename must be specified using -the \f[C]\-o/\-\-output\f[] option. +\f[C]odt\f[], \f[C]docx\f[], and \f[C]epub\f[] output will not be +directed to \f[I]stdout\f[] unless forced with \f[C]\-o\ \-\f[]. Extensions can be individually enabled or disabled by appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name. See Extensions below, for a list of extensions and their names. @@ -347,7 +346,7 @@ To enable bash completion with pandoc, add this to your .IP .nf \f[C] -\ eval\ "$(pandoc\ \-\-bash\-completion)" +eval\ "$(pandoc\ \-\-bash\-completion)" \f[] .fi .RE @@ -386,8 +385,8 @@ List supported output formats, one per line. .RE .TP .B \f[C]\-\-list\-extensions\f[][\f[C]=\f[]\f[I]FORMAT\f[]] -List supported Markdown extensions, one per line, preceded by a -\f[C]+\f[] or \f[C]\-\f[] indicating whether it is enabled by default in +List supported extensions, one per line, preceded by a \f[C]+\f[] or +\f[C]\-\f[] indicating whether it is enabled by default in \f[I]FORMAT\f[]. If \f[I]FORMAT\f[] is not specified, defaults for pandoc\[aq]s Markdown are given. @@ -574,6 +573,10 @@ respectively. The author and time of change is included. \f[C]all\f[] is useful for scripting: only accepting changes from a certain reviewer, say, or before a certain date. +If a paragraph is inserted or deleted, \f[C]track\-changes=all\f[] +produces a span with the class +\f[C]paragraph\-insertion\f[]/\f[C]paragraph\-deletion\f[] before the +affected paragraph break. This option only affects the docx reader. .RS .RE @@ -1484,7 +1487,7 @@ specified .TP .B \f[C]toc\-title\f[] title of table of contents (works only with EPUB, opendocument, odt, -docx) +docx, pptx) .RS .RE .TP @@ -1521,23 +1524,12 @@ stored in the additional variables \f[C]babel\-lang\f[], \f[C]polyglossia\-lang\f[] (LaTeX) and \f[C]context\-lang\f[] (ConTeXt). .RS .PP -Native pandoc \f[C]span\f[]s and \f[C]div\f[]s with the lang attribute -(value in BCP 47) can be used to switch the language in that range. -.RE -.TP -.B \f[C]otherlangs\f[] -a list of other languages used in the document in the YAML metadata, -according to BCP 47. -For example: \f[C]otherlangs:\ [en\-GB,\ fr]\f[]. -This is automatically generated from the \f[C]lang\f[] attributes in all -\f[C]span\f[]s and \f[C]div\f[]s but can be overridden. -Currently only used by LaTeX through the generated -\f[C]babel\-otherlangs\f[] and \f[C]polyglossia\-otherlangs\f[] -variables. -The LaTeX writer outputs polyglossia commands in the text but the -\f[C]babel\-newcommands\f[] variable contains mappings for them to the -corresponding babel. -.RS +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, \f[C]babel\-otherlangs\f[] and +\f[C]polyglossia\-otherlangs\f[] variables will be generated +automatically based on the \f[C]lang\f[] attributes of Spans and Divs in +the document. .RE .TP .B \f[C]dir\f[] @@ -2357,6 +2349,12 @@ to Emacs Muse markup. .PP Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted in \f[C]org\f[] input. +.SS Extension: \f[C]ntb\f[] +.PP +In the \f[C]context\f[] output format this enables the use of Natural +Tables (TABLE) instead of the default Extreme Tables (xtables). +Natural tables allow more fine\-grained global customization but come at +a performance penalty compared to extreme tables. .SH PANDOC\[aq]S MARKDOWN .PP Pandoc understands an extended and slightly revised version of John @@ -3711,6 +3709,23 @@ $endif$ $endfor$ \f[] .fi +.PP +Raw content to include in the document\[aq]s header may be specified +using \f[C]header\-includes\f[]; however, it is important to mark up +this content as raw code for a particular output format, using the +\f[C]raw_attribute\f[] extension), or it will be interpreted as +markdown. +For example: +.IP +.nf +\f[C] +header\-includes: +\-\ ```{=latex} +\ \ \\let\\oldsection\\section +\ \ \\renewcommand{\\section}[1]{\\clearpage\\oldsection{#1}} +\ \ ``` +\f[] +.fi .SS Backslash escapes .SS Extension: \f[C]all_symbols_escapable\f[] .PP @@ -4071,55 +4086,6 @@ Use native pandoc \f[C]Span\f[] blocks for content inside For the most part this should give the same output as \f[C]raw_html\f[], but it makes it easier to write pandoc filters to manipulate groups of inlines. -.SS Extension: \f[C]fenced_divs\f[] -.PP -Allow special fenced syntax for native \f[C]Div\f[] blocks. -A Div starts with a fence containing at least three consecutive colons -plus some attributes. -The attributes may optionally be followed by another string of -consecutive colons. -The attribute syntax is exactly as in fenced code blocks (see Extension: -\f[C]fenced_code_attributes\f[]). -As with fenced code blocks, one can use either attributes in curly -braces or a single unbraced word, which will be treated as a class name. -The Div ends with another line containing a string of at least three -consecutive colons. -The fenced Div should be separated by blank lines from preceding and -following blocks. -.PP -Example: -.IP -.nf -\f[C] -:::::\ {#special\ .sidebar} -Here\ is\ a\ paragraph. - -And\ another. -::::: -\f[] -.fi -.PP -Fenced divs can be nested. -Opening fences are distinguished because they \f[I]must\f[] have -attributes: -.IP -.nf -\f[C] -:::\ Warning\ :::::: -This\ is\ a\ warning. - -:::\ Danger -This\ is\ a\ warning\ within\ a\ warning. -::: -:::::::::::::::::: -\f[] -.fi -.PP -Fences without attributes are always closing fences. -Unlike with fenced code blocks, the number of colons in the closing -fence need not match the number in the opening fence. -However, it can be helpful for visual clarity to use fences of different -lengths to distinguish nested divs from their parents. .SS Extension: \f[C]raw_tex\f[] .PP In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be @@ -4203,13 +4169,15 @@ $\\tuple{a,\ b,\ c}$ \f[] .fi .PP -In LaTeX output, the macro definitions will not be passed through as raw -LaTeX. +Note that LaTeX macros will not be applied if they occur inside inside a +raw span or block marked with the \f[C]raw_attribute\f[] extension. .PP -When \f[C]latex_macros\f[] is disabled, the macro definitions will be -passed through as raw LaTeX, and the raw LaTeX and math will not have -macros applied. +When \f[C]latex_macros\f[] is disabled, the raw LaTeX and math will not +have macros applied. This is usually a better approach when you are targeting LaTeX or PDF. +.PP +Whether or not \f[C]latex_macros\f[] is enabled, the macro definitions +will still be passed through as raw LaTeX. .SS Links .PP Markdown allows links to be specified in several ways. @@ -4405,7 +4373,7 @@ One way to do this is to insert a nonbreaking space after the image: .IP .nf \f[C] -![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\ +![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\ \f[] .fi .PP @@ -4467,12 +4435,67 @@ identifier (LaTeX \f[C]\\caption\f[]), or both (HTML). 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 Spans +.SS Divs and Spans +.PP +Using the \f[C]native_divs\f[] and \f[C]native_spans\f[] extensions (see +above), HTML syntax can be used as part of markdown to create native +\f[C]Div\f[] and \f[C]Span\f[] elements in the pandoc AST (as opposed to +raw HTML). +However, there is also nicer syntax available: +.SS Extension: \f[C]fenced_divs\f[] +.PP +Allow special fenced syntax for native \f[C]Div\f[] blocks. +A Div starts with a fence containing at least three consecutive colons +plus some attributes. +The attributes may optionally be followed by another string of +consecutive colons. +The attribute syntax is exactly as in fenced code blocks (see Extension: +\f[C]fenced_code_attributes\f[]). +As with fenced code blocks, one can use either attributes in curly +braces or a single unbraced word, which will be treated as a class name. +The Div ends with another line containing a string of at least three +consecutive colons. +The fenced Div should be separated by blank lines from preceding and +following blocks. +.PP +Example: +.IP +.nf +\f[C] +:::::\ {#special\ .sidebar} +Here\ is\ a\ paragraph. + +And\ another. +::::: +\f[] +.fi +.PP +Fenced divs can be nested. +Opening fences are distinguished because they \f[I]must\f[] have +attributes: +.IP +.nf +\f[C] +:::\ Warning\ :::::: +This\ is\ a\ warning. + +:::\ Danger +This\ is\ a\ warning\ within\ a\ warning. +::: +:::::::::::::::::: +\f[] +.fi +.PP +Fences without attributes are always closing fences. +Unlike with fenced code blocks, the number of colons in the closing +fence need not match the number in the opening fence. +However, it can be helpful for visual clarity to use fences of different +lengths to distinguish nested divs from their parents. .SS Extension: \f[C]bracketed_spans\f[] .PP A bracketed sequence of inlines, as one would use to begin a link, will -be treated as a span with attributes if it is followed immediately by -attributes: +be treated as a \f[C]Span\f[] with attributes if it is followed +immediately by attributes: .IP .nf \f[C] |