diff options
Diffstat (limited to 'man/pandoc.1')
| -rw-r--r-- | man/pandoc.1 | 946 |
1 files changed, 627 insertions, 319 deletions
diff --git a/man/pandoc.1 b/man/pandoc.1 index 2ffd794f6..0126fc6de 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,5 +1,5 @@ .\"t -.TH PANDOC 1 "July 15, 2015" "" +.TH PANDOC 1 "November 12, 2015" "pandoc 1.15.2.1" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -9,32 +9,46 @@ 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, and (subsets of) Textile, -reStructuredText, HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock -markup, OPML, Emacs Org\-mode, DocBook, txt2tags, EPUB and Word docx; -and it can write plain text, Markdown, reStructuredText, XHTML, HTML 5, -LaTeX (including beamer slide shows), ConTeXt, RTF, OPML, DocBook, -OpenDocument, ODT, Word docx, GNU 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 is installed. -.PP -Pandoc\[aq]s enhanced version of markdown includes syntax for footnotes, +It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored +Markdown, and (subsets of) Textile, reStructuredText, HTML, LaTeX, +MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs Org mode, +DocBook, txt2tags, EPUB, ODT and Word docx; and it can write plain text, +Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored Markdown, +reStructuredText, XHTML, HTML5, LaTeX (including \f[C]beamer\f[] slide +shows), ConTeXt, RTF, OPML, DocBook, OpenDocument, ODT, Word docx, GNU +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. +.PP +Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes, tables, flexible ordered lists, definition lists, fenced code blocks, -superscript, subscript, strikeout, title blocks, automatic tables of -contents, embedded LaTeX math, citations, and markdown inside HTML block -elements. -(These enhancements, described below under Pandoc\[aq]s markdown, can be +superscripts and subscripts, strikeout, metadata blocks, automatic +tables of contents, embedded LaTeX math, citations, and Markdown inside +HTML block elements. +(These enhancements, described below 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 +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. Thus, adding an input or output format requires only adding a reader or writer. +.PP +Because pandoc\[aq]s intermediate representation of a document is less +expressive than many of the formats it converts between, one should not +expect perfect conversions between every format and every other. +Pandoc attempts to preserve the structural elements of a document, but +not formatting details such as margin size. +And some document elements, such as complex tables, may not fit into +pandoc\[aq]s simple document model. +While conversions from pandoc\[aq]s Markdown to all formats aspire to be +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 @@ -77,15 +91,15 @@ pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org .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[] -and \f[C]docx\f[]. +This feature is disabled for binary input formats such as \f[C]EPUB\f[], +\f[C]odt\f[], and \f[C]docx\f[]. .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. -Thus, to convert \f[C]hello.txt\f[] from markdown to LaTeX, you could +Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could type: .IP .nf @@ -94,7 +108,7 @@ pandoc\ \-f\ markdown\ \-t\ latex\ hello.txt \f[] .fi .PP -To convert \f[C]hello.html\f[] from html to markdown: +To convert \f[C]hello.html\f[] from HTML to Markdown: .IP .nf \f[C] @@ -121,13 +135,13 @@ pandoc\ \-o\ hello.tex\ hello.txt \f[] .fi .PP -will convert \f[C]hello.txt\f[] from markdown to LaTeX. +will convert \f[C]hello.txt\f[] from Markdown to LaTeX. If no output file is specified (so that output goes to \f[I]stdout\f[]), 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 unless explicitly specified. .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 @@ -145,14 +159,9 @@ included in the document header, which will only be included if you use the \f[C]\-s/\-\-standalone\f[] option. .SS Creating a PDF .PP -Earlier versions of pandoc came with a program, \f[C]markdown2pdf\f[], -that used pandoc and pdflatex to produce a PDF. -This is no longer needed, since \f[C]pandoc\f[] can now produce -\f[C]pdf\f[] output itself. -To produce a PDF, simply specify an output file with a \f[C]\&.pdf\f[] +To produce a PDF, specify an output file with a \f[C]\&.pdf\f[] extension. -Pandoc will create a latex file and use pdflatex (or another engine, see -\f[C]\-\-latex\-engine\f[]) to convert it to PDF: +By default, pandoc will use LaTeX to convert it to PDF: .IP .nf \f[C] @@ -162,15 +171,32 @@ pandoc\ test.txt\ \-o\ test.pdf .PP Production of a PDF requires that a LaTeX engine be installed (see \f[C]\-\-latex\-engine\f[], below), and assumes that the following LaTeX -packages are available: \f[C]amssymb\f[], \f[C]amsmath\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]url\f[], \f[C]graphicx\f[] -and \f[C]grffile\f[] (if the document contains images), -\f[C]hyperref\f[], \f[C]ulem\f[], \f[C]babel\f[] (if the \f[C]lang\f[] -variable is set), \f[C]fontspec\f[] (if \f[C]xelatex\f[] or -\f[C]lualatex\f[] is used as the LaTeX engine), \f[C]xltxtra\f[] and -\f[C]xunicode\f[] (if \f[C]xelatex\f[] is used). +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]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[]). +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. +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. +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 @@ -180,8 +206,8 @@ 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. -However, this approach does not work under Cygwin, due to problems with -its simulation of symbolic links. +This approach does not work under Cygwin, due to problems with its +simulation of symbolic links. .SH OPTIONS .SS General options .TP @@ -189,15 +215,15 @@ its simulation of symbolic links. Specify input format. \f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[] (JSON version of native AST), \f[C]markdown\f[] (pandoc\[aq]s extended -markdown), \f[C]markdown_strict\f[] (original unextended markdown), -\f[C]markdown_phpextra\f[] (PHP Markdown Extra extended markdown), -\f[C]markdown_github\f[] (github extended markdown), \f[C]commonmark\f[] -(CommonMark markdown), \f[C]textile\f[] (Textile), \f[C]rst\f[] -(reStructuredText), \f[C]html\f[] (HTML), \f[C]docbook\f[] (DocBook), -\f[C]t2t\f[] (txt2tags), \f[C]docx\f[] (docx), \f[C]epub\f[] (EPUB), -\f[C]opml\f[] (OPML), \f[C]org\f[] (Emacs Org\-mode), \f[C]mediawiki\f[] -(MediaWiki markup), \f[C]twiki\f[] (TWiki markup), \f[C]haddock\f[] -(Haddock markup), or \f[C]latex\f[] (LaTeX). +Markdown), \f[C]markdown_strict\f[] (original unextended Markdown), +\f[C]markdown_phpextra\f[] (PHP Markdown Extra), +\f[C]markdown_github\f[] (GitHub\-Flavored Markdown), +\f[C]commonmark\f[] (CommonMark Markdown), \f[C]textile\f[] (Textile), +\f[C]rst\f[] (reStructuredText), \f[C]html\f[] (HTML), \f[C]docbook\f[] +(DocBook), \f[C]t2t\f[] (txt2tags), \f[C]docx\f[] (docx), \f[C]odt\f[] +(ODT), \f[C]epub\f[] (EPUB), \f[C]opml\f[] (OPML), \f[C]org\f[] (Emacs +Org mode), \f[C]mediawiki\f[] (MediaWiki markup), \f[C]twiki\f[] (TWiki +markup), \f[C]haddock\f[] (Haddock markup), or \f[C]latex\f[] (LaTeX). If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[], \f[C]latex\f[], or \f[C]html\f[], the input will be treated as literate Haskell source: see Literate Haskell support, below. @@ -205,10 +231,10 @@ Markdown syntax extensions can be individually enabled or disabled by appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name. So, for example, \f[C]markdown_strict+footnotes+definition_lists\f[] is -strict markdown with footnotes and definition lists enabled, and -\f[C]markdown\-pipe_tables+hard_line_breaks\f[] is pandoc\[aq]s markdown +strict Markdown with footnotes and definition lists enabled, and +\f[C]markdown\-pipe_tables+hard_line_breaks\f[] is pandoc\[aq]s Markdown without pipe tables and with hard line breaks. -See Pandoc\[aq]s markdown, below, for a list of extensions and their +See Pandoc\[aq]s Markdown, below, for a list of extensions and their names. .RS .RE @@ -217,27 +243,27 @@ names. Specify output format. \f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[] (JSON version of native AST), \f[C]plain\f[] (plain text), -\f[C]markdown\f[] (pandoc\[aq]s extended markdown), -\f[C]markdown_strict\f[] (original unextended markdown), -\f[C]markdown_phpextra\f[] (PHP Markdown extra extended markdown), -\f[C]markdown_github\f[] (github extended markdown), \f[C]commonmark\f[] -(CommonMark markdown), \f[C]rst\f[] (reStructuredText), \f[C]html\f[] -(XHTML 1), \f[C]html5\f[] (HTML 5), \f[C]latex\f[] (LaTeX), -\f[C]beamer\f[] (LaTeX beamer slide show), \f[C]context\f[] (ConTeXt), -\f[C]man\f[] (groff man), \f[C]mediawiki\f[] (MediaWiki markup), -\f[C]dokuwiki\f[] (DokuWiki markup), \f[C]textile\f[] (Textile), -\f[C]org\f[] (Emacs Org\-Mode), \f[C]texinfo\f[] (GNU Texinfo), -\f[C]opml\f[] (OPML), \f[C]docbook\f[] (DocBook), \f[C]opendocument\f[] -(OpenDocument), \f[C]odt\f[] (OpenOffice text document), \f[C]docx\f[] -(Word docx), \f[C]haddock\f[] (Haddock markup), \f[C]rtf\f[] (rich text -format), \f[C]epub\f[] (EPUB v2 book), \f[C]epub3\f[] (EPUB v3), -\f[C]fb2\f[] (FictionBook2 e\-book), \f[C]asciidoc\f[] (AsciiDoc), -\f[C]icml\f[] (InDesign ICML), \f[C]slidy\f[] (Slidy HTML and javascript -slide show), \f[C]slideous\f[] (Slideous HTML and javascript slide -show), \f[C]dzslides\f[] (DZSlides HTML5 + javascript slide show), -\f[C]revealjs\f[] (reveal.js HTML5 + javascript slide show), \f[C]s5\f[] -(S5 HTML and javascript slide show), or the path of a custom lua writer -(see Custom writers, below). +\f[C]markdown\f[] (pandoc\[aq]s extended Markdown), +\f[C]markdown_strict\f[] (original unextended Markdown), +\f[C]markdown_phpextra\f[] (PHP Markdown Extra), +\f[C]markdown_github\f[] (GitHub\-Flavored Markdown), +\f[C]commonmark\f[] (CommonMark Markdown), \f[C]rst\f[] +(reStructuredText), \f[C]html\f[] (XHTML), \f[C]html5\f[] (HTML5), +\f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX beamer slide show), +\f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff man), \f[C]mediawiki\f[] +(MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki markup), +\f[C]textile\f[] (Textile), \f[C]org\f[] (Emacs Org mode), +\f[C]texinfo\f[] (GNU Texinfo), \f[C]opml\f[] (OPML), \f[C]docbook\f[] +(DocBook), \f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[] +(OpenOffice text document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[] +(Haddock markup), \f[C]rtf\f[] (rich text format), \f[C]epub\f[] (EPUB +v2 book), \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2 e\-book), +\f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML), +\f[C]slidy\f[] (Slidy HTML and javascript slide show), \f[C]slideous\f[] +(Slideous HTML and javascript slide show), \f[C]dzslides\f[] (DZSlides +HTML5 + javascript slide show), \f[C]revealjs\f[] (reveal.js HTML5 + +javascript slide show), \f[C]s5\f[] (S5 HTML and javascript slide show), +or the path of a custom lua writer (see Custom writers, below). 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. @@ -263,7 +289,7 @@ If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[]. Specify the user data directory to search for pandoc data files. If this option is not specified, the default user data directory will be used. -This is +This is, in Unix: .RS .IP .nf @@ -272,7 +298,7 @@ $HOME/.pandoc \f[] .fi .PP -in unix, +in Windows XP: .IP .nf \f[C] @@ -280,7 +306,7 @@ C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc \f[] .fi .PP -in Windows XP, and +and in Windows Vista or later: .IP .nf \f[C] @@ -288,13 +314,25 @@ C:\\Users\\USERNAME\\AppData\\Roaming\\pandoc \f[] .fi .PP -in Windows 7. -(You can find the default user data directory on your system by looking -at the output of \f[C]pandoc\ \-\-version\f[].) A -\f[C]reference.odt\f[], \f[C]reference.docx\f[], \f[C]default.csl\f[], -\f[C]epub.css\f[], \f[C]templates\f[], \f[C]slidy\f[], -\f[C]slideous\f[], or \f[C]s5\f[] directory placed in this directory -will override pandoc\[aq]s normal defaults. +You can find the default user data directory on your system by looking +at the output of \f[C]pandoc\ \-\-version\f[]. +A \f[C]reference.odt\f[], \f[C]reference.docx\f[], \f[C]epub.css\f[], +\f[C]templates\f[], \f[C]slidy\f[], \f[C]slideous\f[], or \f[C]s5\f[] +directory placed in this directory will override pandoc\[aq]s normal +defaults. +.RE +.TP +.B \f[C]\-\-bash\-completion\f[] +Generate a bash completion script. +To enable bash completion with pandoc, add this to your +\f[C]\&.bashrc\f[]: +.RS +.IP +.nf +\f[C] +\ eval\ "$(pandoc\ \-\-bash\-completion)" +\f[] +.fi .RE .TP .B \f[C]\-\-verbose\f[] @@ -318,9 +356,9 @@ Show usage message. Parse untranslatable HTML codes and LaTeX environments as raw HTML or LaTeX, instead of ignoring them. Affects only HTML and LaTeX input. -Raw HTML can be printed in markdown, reStructuredText, HTML, Slidy, +Raw HTML can be printed in Markdown, reStructuredText, HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX can be printed -in markdown, reStructuredText, LaTeX, and ConTeXt output. +in Markdown, reStructuredText, LaTeX, and ConTeXt output. The default is for the readers to omit untranslatable HTML codes and LaTeX environments. (The LaTeX reader does pass through untranslatable LaTeX @@ -333,11 +371,8 @@ Produce typographically correct output, converting straight quotes to curly quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to en\-dashes, and \f[C]\&...\f[] to ellipses. Nonbreaking spaces are inserted after certain abbreviations, such as -"Mr." (Note: This option is significant only when the input format is -\f[C]markdown\f[], \f[C]markdown_strict\f[], \f[C]textile\f[] or -\f[C]twiki\f[]. -It is selected automatically when the input format is \f[C]textile\f[] -or the output format is \f[C]latex\f[] or \f[C]context\f[], unless +"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.) .RS .RE @@ -367,12 +402,12 @@ Specify a default extension to use when image paths/URLs have no extension. This allows you to use the same source for formats that require different kinds of images. -Currently this option only affects the markdown and LaTeX readers. +Currently this option only affects the Markdown and LaTeX readers. .RS .RE .TP .B \f[C]\-\-filter=\f[]\f[I]EXECUTABLE\f[] -Specify an executable to be used as a filter transforming the Pandoc AST +Specify an executable to be used as a filter transforming the pandoc AST after the input is parsed and before the output is written. The executable should read JSON from stdin and write JSON to stdout. The JSON must be formatted like pandoc\[aq]s own JSON input and output. @@ -402,8 +437,6 @@ Filters may be written in any language. writing filters in Haskell. Those who would prefer to write filters in python can use the module \f[C]pandocfilters\f[], installable from PyPI. -See http://github.com/jgm/pandocfilters for the module and several -examples. There are also pandoc filter libraries in PHP, perl, and javascript/node.js. .PP @@ -449,7 +482,7 @@ Specify the number of spaces per tab (default is 4). .TP .B \f[C]\-\-track\-changes=accept\f[]|\f[C]reject\f[]|\f[C]all\f[] Specifies what to do with insertions and deletions produced by the MS -Word "track\-changes" feature. +Word "Track Changes" feature. \f[C]accept\f[] (the default), inserts all insertions, and ignores all deletions. \f[C]reject\f[] inserts all deletions and ignores insertions. @@ -482,7 +515,7 @@ This option is set automatically for \f[C]pdf\f[], \f[C]epub\f[], .B \f[C]\-\-template=\f[]\f[I]FILE\f[] Use \f[I]FILE\f[] as a custom template for the generated document. Implies \f[C]\-\-standalone\f[]. -See Templates below for a description of template syntax. +See Templates, below, for a description of template syntax. If no extension is specified, an extension corresponding to the writer will be added, so that \f[C]\-\-template=special\f[] looks for \f[C]special.html\f[] for HTML output. @@ -644,13 +677,13 @@ instead of UTF\-8 when this option is selected). .TP .B \f[C]\-\-reference\-links\f[] Use reference\-style links, rather than inline links, in writing -markdown or reStructuredText. +Markdown or reStructuredText. By default inline links are used. .RS .RE .TP .B \f[C]\-\-atx\-headers\f[] -Use ATX style headers in markdown and asciidoc output. +Use ATX\-style headers in Markdown and asciidoc output. The default is to use setext\-style headers for levels 1\-2, and then ATX headers. .RS @@ -659,8 +692,8 @@ ATX headers. .B \f[C]\-\-chapters\f[] Treat top\-level headers as chapters in LaTeX, ConTeXt, and DocBook output. -When the LaTeX template uses the report, book, or memoir class, this -option is implied. +When the LaTeX document class is set to \f[C]report\f[], \f[C]book\f[], +or \f[C]memoir\f[], this option is implied. If \f[C]beamer\f[] is the output format, top\-level headers will become \f[C]\\part{..}\f[]. .RS @@ -692,8 +725,8 @@ Implies \f[C]\-\-number\-sections\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 XeLaTeX and -LuaLaTeX. +This is needed for using advanced OpenType features with +\f[C]xelatex\f[] and \f[C]lualatex\f[]. 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. @@ -704,7 +737,7 @@ then you may want to use \f[C]\-\-no\-tex\-ligatures\f[] without .RE .TP .B \f[C]\-\-listings\f[] -Use listings package for LaTeX code blocks +Use the \f[C]listings\f[] package for LaTeX code blocks .RS .RE .TP @@ -722,7 +755,7 @@ Headers above this level in the hierarchy are used to divide the slide show into sections; headers below this level create subheads within a slide. The default is to set the slide level based on the contents of the -document; see Structuring the slide show, below. +document; see Structuring the slide show. .RS .RE .TP @@ -741,12 +774,13 @@ documents. \f[C]javascript\f[] obfuscates them using javascript. \f[C]references\f[] obfuscates them by printing their letters as decimal or hexadecimal character references. +The default is \f[C]javascript\f[]. .RS .RE .TP .B \f[C]\-\-id\-prefix=\f[]\f[I]STRING\f[] Specify a prefix to be added to all automatically generated identifiers -in HTML and DocBook output, and to footnote numbers in markdown output. +in HTML and DocBook output, and to footnote numbers in Markdown output. This is useful for preventing duplicate identifiers when generating fragments to be included in other pages. .RS @@ -814,7 +848,7 @@ If it is not found there, sensible defaults will be used. Use the specified image as the EPUB cover. It is recommended that the image be less than 1000px in width and height. -Note that in a markdown source document you can also specify +Note that in a Markdown source document you can also specify \f[C]cover\-image\f[] in a YAML metadata block (see EPUB Metadata, below). .RS @@ -822,8 +856,7 @@ below). .TP .B \f[C]\-\-epub\-metadata=\f[]\f[I]FILE\f[] Look in the specified XML file for metadata for the EPUB. -The file should contain a series of Dublin Core elements, as documented -at http://dublincore.org/documents/dces/. +The file should contain a series of Dublin Core elements. For example: .RS .IP @@ -842,7 +875,7 @@ which should be in ISO 8601 format), \f[C]<dc:language>\f[] (from the \f[C]<dc:identifier\ id="BookId">\f[] (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. .PP -Note: if the source document is markdown, a YAML metadata block in the +Note: if the source document is Markdown, a YAML metadata block in the document can be used instead. See below under EPUB Metadata. .RE @@ -951,20 +984,20 @@ only relevant with \f[C]pandoc\-citeproc\f[]. .RE .TP .B \f[C]\-\-natbib\f[] -Use natbib for citations in LaTeX output. +Use \f[C]natbib\f[] for citations in LaTeX output. This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or with PDF output. It is intended for use in producing a LaTeX file that can be processed -with pdflatex and bibtex. +with \f[C]bibtex\f[]. .RS .RE .TP .B \f[C]\-\-biblatex\f[] -Use biblatex for citations in LaTeX output. +Use \f[C]biblatex\f[] for citations in LaTeX output. This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or with PDF output. It is intended for use in producing a LaTeX file that can be processed -with pdflatex and bibtex or biber. +with \f[C]bibtex\f[] or \f[C]biber\f[]. .RS .RE .SS Math rendering in HTML @@ -1057,7 +1090,7 @@ with the \f[C]\-o\f[] option, or \f[C]\-\f[] (for \f[I]stdout\f[]) if no output file was specified. The remaining lines contain the command\-line arguments, one per line, in the order they appear. -These do not include regular Pandoc options and their arguments, but do +These do not include regular pandoc options and their arguments, but do include any options appearing after a \f[C]\-\-\f[] separator at the end of the line. .RS @@ -1065,7 +1098,7 @@ of the line. .TP .B \f[C]\-\-ignore\-args\f[] Ignore command\-line arguments (for use in wrapper scripts). -Regular Pandoc options are not ignored. +Regular pandoc options are not ignored. Thus, for example, .RS .IP @@ -1092,42 +1125,66 @@ To see the default template that is used, just type .IP .nf \f[C] -pandoc\ \-D\ FORMAT +pandoc\ \-D\ *FORMAT* \f[] .fi .PP -where \f[C]FORMAT\f[] is the name of the output format. +where \f[I]FORMAT\f[] is the name of the output format. A custom template can be specified using the \f[C]\-\-template\f[] option. You can also override the system default templates for a given output -format \f[C]FORMAT\f[] by putting a file -\f[C]templates/default.FORMAT\f[] in the user data directory (see +format \f[I]FORMAT\f[] by putting a file +\f[C]templates/default.*FORMAT*\f[] in the user data directory (see \f[C]\-\-data\-dir\f[], above). \f[I]Exceptions:\f[] For \f[C]odt\f[] output, customize the \f[C]default.opendocument\f[] template. For \f[C]pdf\f[] output, customize the \f[C]default.latex\f[] template. .PP -Templates may contain \f[I]variables\f[]. -Variable names are sequences of alphanumerics, \f[C]\-\f[], and -\f[C]_\f[], starting with a letter. -A variable name surrounded by \f[C]$\f[] signs will be replaced by its -value. -For example, the string \f[C]$title$\f[] in +Templates contain \f[I]variables\f[], which allow for the inclusion of +arbitrary information at any point in the file. +Variables may be set within the document using YAML metadata blocks. +They may also be set at the command line using the +\f[C]\-V/\-\-variable\f[] option: variables set in this way override +metadata fields with the same name. +.SS Variables set by pandoc +.PP +Some variables are set automatically by pandoc. +These vary somewhat depending on the output format, but include metadata +fields as well as the following: +.TP +.B \f[C]title\f[], \f[C]author\f[], \f[C]date\f[] +allow identification of basic aspects of the document. +Included in PDF metadata through LaTeX and ConTeXt. +These can be set through a pandoc title block, which allows for multiple +authors, or through a YAML metadata block: +.RS .IP .nf \f[C] -<title>$title$</title> +\-\-\- +author: +\-\ Aristotle +\-\ Peter\ Abelard +\&... \f[] .fi -.PP -will be replaced by the document title. -.PP -To write a literal \f[C]$\f[] in a template, use \f[C]$$\f[]. -.PP -Some variables are set automatically by pandoc. -These vary somewhat depending on the output format, but include metadata -fields (such as \f[C]title\f[], \f[C]author\f[], and \f[C]date\f[]) as -well as the following: +.RE +.TP +.B \f[C]subtitle\f[] +document subtitle; also used as subject in PDF metadata +.RS +.RE +.TP +.B \f[C]abstract\f[] +document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx +.RS +.RE +.TP +.B \f[C]keywords\f[] +list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may +be repeated as for \f[C]author\f[], above +.RS +.RE .TP .B \f[C]header\-includes\f[] contents specified by \f[C]\-H/\-\-include\-in\-header\f[] (may have @@ -1141,6 +1198,11 @@ specified .RS .RE .TP +.B \f[C]toc\-title\f[] +title of table of contents (works only with EPUB and docx) +.RS +.RE +.TP .B \f[C]include\-before\f[] contents specified by \f[C]\-B/\-\-include\-before\-body\f[] (may have multiple values) @@ -1157,12 +1219,57 @@ multiple values) body of document .RS .RE +.SS Language variables .TP .B \f[C]lang\f[] -language code for HTML or LaTeX documents +identifies the main language of the document, using a code according to +BCP 47 (e.g. +\f[C]en\f[] or \f[C]en\-GB\f[]). +For some output formats, pandoc will convert it to an appropriate format +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 overriden. +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 +.RE +.TP +.B \f[C]dir\f[] +the base direction of the document, either \f[C]rtl\f[] +(right\-to\-left) or \f[C]ltr\f[] (left\-to\-right). +.RS +.PP +For bidirectional documents, native pandoc \f[C]span\f[]s and +\f[C]div\f[]s with the \f[C]dir\f[] attribute (value \f[C]rtl\f[] or +\f[C]ltr\f[]) can be used to override the base direction in some output +formats. +This may not always be necessary if the final renderer (e.g. +the browser, when generating HTML) supports the Unicode Bidirectional +Algorithm. +.PP +When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[] +engine is fully supported (use \f[C]\-\-latex\-engine=xelatex\f[]). +.RE +.SS Variables for slides +.PP +Variables are available for producing slide shows with pandoc, including +all reveal.js configuration options. +.TP .B \f[C]slidy\-url\f[] base URL for Slidy documents (defaults to \f[C]http://www.w3.org/Talks/Tools/Slidy2\f[]) @@ -1184,133 +1291,219 @@ base URL for reveal.js documents (defaults to \f[C]reveal.js\f[]) .RS .RE .TP -.B \f[C]theme\f[] -reveal.js or LaTeX beamer theme -.RS -.RE -.TP -.B \f[C]transition\f[] -reveal.js transition +.B \f[C]theme\f[], \f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], \f[C]outertheme\f[] +themes for LaTeX \f[C]beamer\f[] documents .RS .RE +.SS Variables for LaTeX +.PP +LaTeX variables are used when creating a PDF. .TP .B \f[C]fontsize\f[] -font size (10pt, 11pt, 12pt) for LaTeX documents +font size for body text (e.g. +\f[C]10pt\f[], \f[C]12pt\f[]) .RS .RE .TP .B \f[C]documentclass\f[] -document class for LaTeX documents +document class, e.g. +\f[C]article\f[], \f[C]report\f[], \f[C]book\f[], \f[C]memoir\f[] .RS .RE .TP .B \f[C]classoption\f[] -option for LaTeX documentclass, e.g. +option for document class, e.g. \f[C]oneside\f[]; may be repeated for multiple options .RS .RE .TP .B \f[C]geometry\f[] -options for LaTeX \f[C]geometry\f[] class, e.g. +option for \f[C]geometry\f[] package, e.g. \f[C]margin=1in\f[]; may be repeated for multiple options .RS .RE .TP .B \f[C]linestretch\f[] -adjusts line spacing (requires the \f[C]setspace\f[] package) +adjusts line spacing using the \f[C]setspace\f[] package, e.g. +\f[C]1.25\f[], \f[C]1.5\f[] .RS .RE .TP .B \f[C]fontfamily\f[] -font package to use for LaTeX documents (with pdflatex): TeXLive has -\f[C]bookman\f[] (Bookman), \f[C]utopia\f[] or \f[C]fourier\f[] -(Utopia), \f[C]fouriernc\f[] (New Century Schoolbook), \f[C]times\f[] or -\f[C]txfonts\f[] (Times), \f[C]mathpazo\f[] or \f[C]pxfonts\f[] or -\f[C]mathpple\f[] (Palatino), \f[C]libertine\f[] (Linux Libertine), -\f[C]arev\f[] (Arev Sans), and the default \f[C]lmodern\f[], among -others. +font package for use with \f[C]pdflatex\f[]: TeX Live includes many +options, documented in the LaTeX Font Catalogue. +The default is Latin Modern. +.RS +.RE +.TP +.B \f[C]fontfamilyoptions\f[] +options for package used as \f[C]fontfamily\f[]: e.g. +\f[C]osf,sc\f[] with \f[C]fontfamily\f[] set to \f[C]mathpazo\f[] +provides Palatino with old\-style figures and true small caps; may be +repeated for multiple options .RS .RE .TP .B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] -fonts for LaTeX documents (works only with xelatex and lualatex). -Note that if \f[C]CJKmainfont\f[] is used, the \f[C]xeCJK\f[] package +font families for use with \f[C]xelatex\f[] or \f[C]lualatex\f[]: take +the name of any system font, using the \f[C]fontspec\f[] package. +Note that if \f[C]CJKmainfont\f[] is used, the \f[C]xecjk\f[] package must be available. .RS .RE .TP -.B \f[C]colortheme\f[] -colortheme for LaTeX beamer documents +.B \f[C]mainfontoptions\f[], \f[C]sansfontoptions\f[], \f[C]monofontoptions\f[], \f[C]mathfontoptions\f[], \f[C]CJKoptions\f[] +options to use with \f[C]mainfont\f[], \f[C]sansfont\f[], +\f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] in +\f[C]xelatex\f[] and \f[C]lualatex\f[]. +Allow for any choices available through \f[C]fontspec\f[], such as the +OpenType features \f[C]Numbers=OldStyle,Numbers=Proportional\f[]. +May be repeated for multiple options. .RS .RE .TP -.B \f[C]fonttheme\f[] -fonttheme for LaTeX beamer documents +.B \f[C]fontenc\f[] +allows font encoding to be specified through \f[C]fontenc\f[] package +(with \f[C]pdflatex\f[]); default is \f[C]T1\f[] (see guide to LaTeX +font encodings) .RS .RE .TP -.B \f[C]linkcolor\f[] -color for internal links in LaTeX documents (\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]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[] .RS .RE .TP -.B \f[C]toccolor\f[] -color for links in table of contents in LaTeX documents +.B \f[C]hidelinks\f[] +enables \f[C]hidelinks\f[] option for \f[C]hyperref\f[], disabling link +color .RS .RE .TP -.B \f[C]urlcolor\f[] -color for external links in LaTeX documents +.B \f[C]links\-as\-notes\f[] +causes links to be printed as footnotes .RS .RE .TP -.B \f[C]citecolor\f[] -color for citation links in LaTeX documents +.B \f[C]indent\f[] +uses document class settings for indentation (the default LaTeX template +otherwise removes indentation and adds space between paragraphs) .RS .RE .TP -.B \f[C]links\-as\-notes\f[] -causes links to be printed as footnotes in LaTeX documents +.B \f[C]subparagraph\f[] +disables default behavior of LaTeX template that redefines +(sub)paragraphs as sections, changing the appearance of nested headings +in some classes .RS .RE .TP .B \f[C]toc\f[] -include table of contents in LaTeX documents +include table of contents (can also be set using +\f[C]\-\-toc/\-\-table\-of\-contents\f[]) .RS .RE .TP .B \f[C]toc\-depth\f[] -level of section to include in table of contents in LaTeX documents +level of section to include in table of contents .RS .RE .TP -.B \f[C]toc\-title\f[] -title of table of contents (works only with EPUB and docx) +.B \f[C]lof\f[], \f[C]lot\f[] +include list of figures, list of tables .RS .RE .TP -.B \f[C]lof\f[] -include list of figures in LaTeX documents +.B \f[C]bibliography\f[] +bibliography to use for resolving references .RS .RE .TP -.B \f[C]lot\f[] -include list of tables in LaTeX documents +.B \f[C]biblio\-style\f[] +bibliography style, when used with \f[C]\-\-natbib\f[] .RS .RE +.SS Variables for ConTeXt .TP -.B \f[C]bibliography\f[] -bibliography to use for resolving references +.B \f[C]papersize\f[] +paper size, e.g. +\f[C]letter\f[], \f[C]A4\f[], \f[C]landscape\f[] (see ConTeXt Paper +Setup); may be repeated for multiple options .RS .RE .TP -.B \f[C]biblio\-style\f[] -bibliography style in LaTeX, when used with \f[C]\-\-natbib\f[] +.B \f[C]layout\f[] +options for page margins and text arrangement (see ConTeXt Layout); may +be repeated for multiple options +.RS +.RE +.TP +.B \f[C]fontsize\f[] +font size for body text (e.g. +\f[C]10pt\f[], \f[C]12pt\f[]) .RS .RE .TP +.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[] +font families: take the name of any system font (see ConTeXt Font +Switching) +.RS +.RE +.TP +.B \f[C]linkcolor\f[] +color for links, e.g. +\f[C]red\f[], \f[C]blue\f[] (see ConTeXt Color) +.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 +multiple options +.RS +.RE +.TP +.B \f[C]whitespace\f[] +spacing between paragraphs, e.g. +\f[C]none\f[], \f[C]small\f[] (using \f[C]setupwhitespace\f[]) +.RS +.RE +.TP +.B \f[C]interlinespace\f[] +adjusts line spacing, e.g. +\f[C]4ex\f[] (using \f[C]setupinterlinespace\f[]); may be repeated for +multiple options +.RS +.RE +.TP +.B \f[C]headertext\f[], \f[C]footertext\f[] +text to be placed in running header or footer (see ConTeXt Headers and +Footers); may be repeated up to four times for different placement +.RS +.RE +.TP +.B \f[C]pagenumbering\f[] +page number style and location (using \f[C]setuppagenumbering\f[]); may +be repeated for multiple options +.RS +.RE +.TP +.B \f[C]toc\f[] +include table of contents (can also be set using +\f[C]\-\-toc/\-\-table\-of\-contents\f[]) +.RS +.RE +.TP +.B \f[C]lof\f[], \f[C]lot\f[] +include list of figures, list of tables +.RS +.RE +.SS Variables for man pages +.TP .B \f[C]section\f[] section number in man pages .RS @@ -1325,10 +1518,34 @@ header in man pages footer in man pages .RS .RE +.TP +.B \f[C]adjusting\f[] +adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center +(\f[C]c\f[]), or both (\f[C]b\f[]) margins +.RS +.RE +.TP +.B \f[C]hyphenate\f[] +if \f[C]true\f[] (the default), hyphenation will be used +.RS +.RE +.SS Using variables in templates +.PP +Variable names are sequences of alphanumerics, \f[C]\-\f[], and +\f[C]_\f[], starting with a letter. +A variable name surrounded by \f[C]$\f[] signs will be replaced by its +value. +For example, the string \f[C]$title$\f[] in +.IP +.nf +\f[C] +<title>$title$</title> +\f[] +.fi +.PP +will be replaced by the document title. .PP -Variables may be set at the command line using the -\f[C]\-V/\-\-variable\f[] option. -Variables set in this way override metadata fields with the same name. +To write a literal \f[C]$\f[] in a template, use \f[C]$$\f[]. .PP Templates may contain conditionals. The syntax is as follows: @@ -1383,22 +1600,21 @@ If you use custom templates, you may need to revise them as pandoc changes. We recommend tracking the changes in the default templates, and modifying your custom templates accordingly. -An easy way to do this is to fork the pandoc\-templates repository -(http://github.com/jgm/pandoc\-templates) and merge in changes after -each pandoc release. +An easy way to do this is to fork the pandoc\-templates repository and +merge in changes after each pandoc release. .SH PANDOC\[aq]S MARKDOWN .PP Pandoc understands an extended and slightly revised version of John -Gruber\[aq]s markdown syntax. +Gruber\[aq]s Markdown syntax. This document explains the syntax, noting differences from standard -markdown. +Markdown. Except where noted, these differences can be suppressed by using the \f[C]markdown_strict\f[] format instead of \f[C]markdown\f[]. An extensions can be enabled by adding \f[C]+EXTENSION\f[] to the format name and disabled by adding \f[C]\-EXTENSION\f[]. -For example, \f[C]markdown_strict+footnotes\f[] is strict markdown with +For example, \f[C]markdown_strict+footnotes\f[] is strict Markdown with footnotes enabled, while \f[C]markdown\-footnotes\-pipe_tables\f[] is -pandoc\[aq]s markdown without footnotes or pipe tables. +pandoc\[aq]s Markdown without footnotes or pipe tables. .SS Philosophy .PP Markdown is designed to be easy to write, and, even more importantly, @@ -1415,8 +1631,8 @@ This principle has guided pandoc\[aq]s decisions in finding syntax for tables, footnotes, and other extensions. .PP There is, however, one respect in which pandoc\[aq]s aims are different -from the original aims of markdown. -Whereas markdown was originally designed with HTML generation in mind, +from the original aims of Markdown. +Whereas Markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other, non\-HTMLish ways of representing important document @@ -1436,7 +1652,7 @@ Note: in multiline and grid table cells, this is the only way to create a hard line break, since trailing spaces in the cells are ignored. .SS Headers .PP -There are two kinds of headers, Setext and atx. +There are two kinds of headers: Setext and ATX. .SS Setext\-style headers .PP A setext\-style header is a line of text "underlined" with a row of @@ -1455,9 +1671,9 @@ A\ level\-two\ header .PP The header text can contain inline formatting, such as emphasis (see Inline formatting, below). -.SS Atx\-style headers +.SS ATX\-style headers .PP -An Atx\-style header consists of one to six \f[C]#\f[] signs and a line +An ATX\-style header consists of one to six \f[C]#\f[] signs and a line of text, optionally followed by any number of \f[C]#\f[] signs. The number of \f[C]#\f[] signs at the beginning of the line is the header level: @@ -1479,7 +1695,7 @@ As with setext\-style headers, the header text can contain formatting: .fi .SS Extension: \f[C]blank_before_header\f[] .PP -Standard markdown syntax does not require a blank line before a header. +Standard Markdown syntax does not require a blank line before a header. Pandoc does require this (except, of course, at the beginning of the document). The reason for the requirement is that it is all too easy for a @@ -1581,28 +1797,27 @@ Identifier T} _ T{ -Header identifiers in HTML +\f[C]Header\ identifiers\ in\ HTML\f[] T}@T{ \f[C]header\-identifiers\-in\-html\f[] T} T{ -\f[I]Dogs\f[]?\-\-in \f[I]my\f[] house? +\f[C]*Dogs*?\-\-in\ *my*\ house?\f[] T}@T{ \f[C]dogs\-\-in\-my\-house\f[] T} T{ -HTML, S5, or RTF? +\f[C][HTML],\ [S5],\ or\ [RTF]?\f[] T}@T{ \f[C]html\-s5\-or\-rtf\f[] T} T{ -3. -Applications +\f[C]3.\ Applications\f[] T}@T{ \f[C]applications\f[] T} T{ -33 +\f[C]33\f[] T}@T{ \f[C]section\f[] T} @@ -1699,7 +1914,7 @@ See\ [foo] Markdown uses email conventions for quoting blocks of text. A block quotation is one or more paragraphs or other block elements (such as lists or headers), with each line preceded by a \f[C]>\f[] -character and a space. +character and an optional space. (The \f[C]>\f[] need not start at the left margin, but it should not be indented more than three spaces.) .IP @@ -1737,9 +1952,21 @@ That is, block quotes can be nested: >\ >\ A\ block\ quote\ within\ a\ block\ quote. \f[] .fi +.PP +If the \f[C]>\f[] character is followed by an optional space, that space +will be considered part of the block quote marker and not part of the +indentation of the contents. +Thus, to put an indented code block in a block quote, you need five +spaces after the \f[C]>\f[]: +.IP +.nf +\f[C] +>\ \ \ \ \ code +\f[] +.fi .SS Extension: \f[C]blank_before_blockquote\f[] .PP -Standard markdown syntax does not require a blank line before a block +Standard Markdown syntax does not require a blank line before a block quote. Pandoc does require this (except, of course, at the beginning of the document). @@ -1778,7 +2005,7 @@ Note: blank lines in the verbatim text need not begin with four spaces. .SS Fenced code blocks .SS Extension: \f[C]fenced_code_blocks\f[] .PP -In addition to standard indented code blocks, Pandoc supports +In addition to standard indented code blocks, pandoc supports \f[I]fenced\f[] code blocks. These begin with a row of three or more tildes (\f[C]~\f[]) and end with a row of tildes that must be at least as long as the starting row. @@ -1884,7 +2111,7 @@ For more information on highlighting, see Syntax highlighting, below. A line block is a sequence of lines beginning with a vertical bar (\f[C]|\f[]) followed by a space. The division into lines will be preserved in the output, as will any -leading spaces; otherwise, the lines will be formatted as markdown. +leading spaces; otherwise, the lines will be formatted as Markdown. This is useful for verse and addresses: .IP .nf @@ -1958,7 +2185,7 @@ List items look best if subsequent lines are flush with the first line \f[] .fi .PP -But markdown also allows a "lazy" format: +But Markdown also allows a "lazy" format: .IP .nf \f[C] @@ -2007,7 +2234,7 @@ The nested list must be indented four spaces or one tab: \f[] .fi .PP -As noted above, markdown allows you to write list items "lazily," +As noted above, Markdown allows you to write list items "lazily," instead of indenting continuation lines. However, if there are multiple paragraphs or other blocks in a list item, the first line of each must be indented. @@ -2026,12 +2253,12 @@ list\ item. .fi .PP \f[B]Note:\f[] Although the four\-space rule for continuation paragraphs -comes from the official markdown syntax guide, the reference +comes from the official Markdown syntax guide, the reference implementation, \f[C]Markdown.pl\f[], does not follow it. So pandoc will give different results than \f[C]Markdown.pl\f[] when authors have indented continuation paragraphs fewer than four spaces. .PP -The markdown syntax guide is not explicit whether the four\-space rule +The Markdown syntax guide is not explicit whether the four\-space rule applies to \f[I]all\f[] block\-level content in a list item; it only mentions paragraphs and code blocks. But it implies that the rule applies to all block\-level content @@ -2041,7 +2268,7 @@ But it implies that the rule applies to all block\-level content Ordered lists work just like bulleted lists, except that the items begin with enumerators rather than bullets. .PP -In standard markdown, enumerators are decimal numbers followed by a +In standard Markdown, enumerators are decimal numbers followed by a period and a space. The numbers themselves are ignored, so there is no difference between this list: @@ -2065,7 +2292,7 @@ and this one: .fi .SS Extension: \f[C]fancy_lists\f[] .PP -Unlike standard markdown, Pandoc allows ordered list items to be marked +Unlike standard Markdown, pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to arabic numerals. List markers may be enclosed in parentheses or followed by a single @@ -2157,7 +2384,7 @@ one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces. -However, as with other markdown lists, you can "lazily" omit indentation +However, as with other Markdown lists, you can "lazily" omit indentation except at the beginning of a paragraph or other block element: .IP .nf @@ -2247,7 +2474,7 @@ Consider this source: .fi .PP Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags -around "First", "Second", or "Third"), while markdown puts \f[C]<p>\f[] +around "First", "Second", or "Third"), while Markdown puts \f[C]<p>\f[] tags around "Second" and "Third" (but not "First"), because of the blank space around "Third". Pandoc follows a simple rule: if the text is followed by a blank line, @@ -2257,7 +2484,7 @@ treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. (Note: Pandoc works this way even when the \f[C]markdown_strict\f[] format is specified. -This behavior is consistent with the official markdown syntax +This behavior is consistent with the official Markdown syntax description, even though it is different from that of \f[C]Markdown.pl\f[].) .SS Ending a list @@ -2273,7 +2500,7 @@ What if you want to put an indented code block after a list? \f[] .fi .PP -Trouble! Here pandoc (like other markdown implementations) will treat +Trouble! Here pandoc (like other Markdown implementations) will treat \f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and not as a code block. .PP @@ -2427,7 +2654,7 @@ In multiline tables, the table parser pays attention to the widths of the columns, and the writers try to reproduce these relative widths in the output. So, if you find that one of the columns is too narrow in the output, try -widening it in the markdown source. +widening it in the Markdown source. .PP Headers may be omitted in multiline tables as well as simple tables: .IP @@ -2492,7 +2719,7 @@ Pipe tables look like this: \f[] .fi .PP -The syntax is the same as in PHP markdown extra. +The syntax is identical to PHP Markdown Extra tables. The beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. @@ -2520,7 +2747,7 @@ 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. .PP -Note: Pandoc also recognizes pipe tables of the following form, as can +Note: pandoc also recognizes pipe tables of the following form, as can be produced by Emacs\[aq] orgtbl\-mode: .IP .nf @@ -2653,7 +2880,7 @@ A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank line. (Note that, because of the way pandoc concatenates input files when several are provided, you may also keep the metadata in a separate YAML -file and pass it to pandoc as an argument, along with your markdown +file and pass it to pandoc as an argument, along with your Markdown files: .IP .nf @@ -2668,7 +2895,7 @@ with \f[C]\-\-\-\f[] or \f[C]\&...\f[].) Metadata will be taken from the fields of the YAML object and added to any existing document metadata. Metadata can contain lists and objects (nested arbitrarily), but all -string scalars will be interpreted as markdown. +string scalars will be interpreted as Markdown. Fields with names ending in an underscore will be ignored by pandoc. (They may be given a role by external processors.) .PP @@ -2677,7 +2904,7 @@ The metadata fields will be combined through a \f[I]left\-biased union\f[]: if two metadata blocks attempt to set the same field, the value from the first block will be taken. .PP -When pandoc is used with \f[C]\-t\ markdown\f[] to create a markdown +When pandoc is used with \f[C]\-t\ markdown\f[] to create a Markdown document, a YAML metadata block will be produced only if the \f[C]\-s/\-\-standalone\f[] option is used. All of the metadata will appear in a single block at the beginning of @@ -2709,7 +2936,7 @@ abstract:\ | .PP Template variables will be set automatically from the metadata. Thus, for example, in writing HTML, the variable \f[C]abstract\f[] will -be set to the HTML equivalent of the markdown in the \f[C]abstract\f[] +be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[] field: .IP .nf @@ -2766,7 +2993,7 @@ instead of \f[] .fi .PP -This rule is easier to remember than standard markdown\[aq]s rule, which +This rule is easier to remember than standard Markdown\[aq]s rule, which allows only the following characters to be backslash\-escaped: .IP .nf @@ -2776,7 +3003,7 @@ allows only the following characters to be backslash\-escaped: .fi .PP (However, if the \f[C]markdown_strict\f[] format is used, the standard -markdown rule will be used.) +Markdown rule will be used.) .PP A backslash\-escaped space is parsed as a nonbreaking space. It will appear in TeX output as \f[C]~\f[] and in HTML and XML as @@ -2787,7 +3014,7 @@ a backslash occurring at the end of a line) is parsed as a hard line break. It will appear in TeX output as \f[C]\\\\\f[] and in HTML as \f[C]<br\ />\f[]. -This is a nice alternative to markdown\[aq]s "invisible" way of +This is a nice alternative to Markdown\[aq]s "invisible" way of indicating hard line breaks using two trailing spaces on a line. .PP Backslash escapes do not work in verbatim contexts. @@ -2801,9 +3028,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 uses the \f[C]csquotes\f[] package, pandoc -will detect automatically this and use \f[C]\\enquote{...}\f[] for -quoted text. +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. .SS Inline formatting .SS Emphasis .PP @@ -2902,7 +3129,7 @@ The general rule is that a verbatim span starts with a string of consecutive backticks (optionally followed by a space) and ends with a string of the same number of backticks (optionally preceded by a space). .PP -Note that backslash\-escapes (and other markdown constructs) do not work +Note that backslash\-escapes (and other Markdown constructs) do not work in verbatim contexts: .IP .nf @@ -2948,14 +3175,13 @@ delimiters. TeX math will be printed in all output formats. How it is rendered depends on the output format: .TP -.B Markdown, LaTeX, Org\-Mode, ConTeXt +.B Markdown, LaTeX, Emacs Org mode, ConTeXt It will appear verbatim between \f[C]$\f[] characters. .RS .RE .TP .B reStructuredText -It will be rendered using an interpreted text role \f[C]:math:\f[], as -described here +It will be rendered using an interpreted text role \f[C]:math:\f[]. .RS .RE .TP @@ -2990,9 +3216,9 @@ otherwise appear verbatim. .RS .RE .TP -.B Docbook +.B DocBook If the \f[C]\-\-mathml\f[] flag is used, it will be rendered using -mathml in an \f[C]inlineequation\f[] or \f[C]informalequation\f[] tag. +MathML in an \f[C]inlineequation\f[] or \f[C]informalequation\f[] tag. Otherwise it will be rendered, if possible, using unicode characters. .RS .RE @@ -3043,8 +3269,8 @@ is at \f[C]/cgi\-bin/mimetex.cgi\f[]. If the \f[C]\-\-gladtex\f[] option is used, TeX formulas will be enclosed in \f[C]<eq>\f[] tags in the HTML output. The resulting \f[C]htex\f[] file may then be processed by gladTeX, which -will produce image files for each formula and an \f[C]html\f[] file with -links to these images. +will produce image files for each formula and an HTML file with links to +these images. So, the procedure is: .RS 4 .IP @@ -3075,7 +3301,7 @@ The MathJax script will be used to render it as formulas. Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and \f[C]&\f[] are interpreted literally). -(Technically this is not an extension, since standard markdown allows +(Technically this is not an extension, since standard Markdown allows it, but it has been made an extension so that it can be disabled if desired.) .PP @@ -3084,16 +3310,16 @@ DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats. .SS Extension: \f[C]markdown_in_html_blocks\f[] .PP -Standard markdown allows you to include HTML "blocks": blocks of HTML +Standard Markdown allows you to include HTML "blocks": blocks of HTML between balanced tags that are separated from the surrounding text with blank lines, and start and end at the left margin. -Within these blocks, everything is interpreted as HTML, not markdown; so +Within these blocks, everything is interpreted as HTML, not Markdown; so (for example), \f[C]*\f[] does not signify emphasis. .PP Pandoc behaves this way when the \f[C]markdown_strict\f[] format is used; but by default, pandoc interprets material between HTML block tags -as markdown. -Thus, for example, Pandoc will turn +as Markdown. +Thus, for example, pandoc will turn .IP .nf \f[C] @@ -3122,13 +3348,13 @@ into whereas \f[C]Markdown.pl\f[] will preserve it as is. .PP There is one exception to this rule: text between \f[C]<script>\f[] and -\f[C]<style>\f[] tags is not interpreted as markdown. +\f[C]<style>\f[] tags is not interpreted as Markdown. .PP -This departure from standard markdown should make it easier to mix -markdown with HTML block elements. -For example, one can surround a block of markdown text with +This departure from standard Markdown should make it easier to mix +Markdown with HTML block elements. +For example, one can surround a block of Markdown text with \f[C]<div>\f[] tags without preventing it from being interpreted as -markdown. +Markdown. .SS Extension: \f[C]native_divs\f[] .PP Use native pandoc \f[C]Div\f[] blocks for content inside \f[C]<div>\f[] @@ -3172,7 +3398,7 @@ Age\ &\ Frequency\ \\\\\ \\hline .fi .PP the material between the begin and end tags will be interpreted as raw -LaTeX, not as markdown. +LaTeX, not as Markdown. .PP Inline LaTeX is ignored in output formats other than Markdown, LaTeX, and ConTeXt. @@ -3295,7 +3521,7 @@ See\ [my\ website][]. \f[] .fi .PP -Note: In \f[C]Markdown.pl\f[] and most other markdown implementations, +Note: In \f[C]Markdown.pl\f[] and most other Markdown implementations, reference link definitions cannot occur in nested constructions such as list items or block quotes. Pandoc lifts this arbitrary seeming restriction. @@ -3324,7 +3550,7 @@ See\ [my\ website]. .SS Internal links .PP To link to another section of the same document, use the automatically -generated identifier (see Header identifiers, below). +generated identifier (see Header identifiers). For example: .IP .nf @@ -3379,13 +3605,13 @@ 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 .SS Footnotes .SS Extension: \f[C]footnotes\f[] .PP -Pandoc\[aq]s markdown allows footnotes, using the following syntax: +Pandoc\[aq]s Markdown allows footnotes, using the following syntax: .IP .nf \f[C] @@ -3520,18 +3746,49 @@ T}@T{ T} .TE .PP -Note that \f[C]\&.bib\f[] can generally be used with both BibTeX and -BibLaTeX files, but you can use \f[C]\&.bibtex\f[] to force BibTeX. +Note that \f[C]\&.bib\f[] can be used with both BibTeX and BibLaTeX +files; use \f[C]\&.bibtex\f[] to force BibTeX. .PP Note that \f[C]pandoc\-citeproc\ \-\-bib2json\f[] and \f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce \f[C]\&.json\f[] and \f[C]\&.yaml\f[] files from any of the supported formats. .PP -In\-field markup: In bibtex and biblatex databases, pandoc\-citeproc -parses (a subset of) LaTeX markup; in CSL JSON databases, an HTML\-like -markup (specs); and in CSL YAML databases, pandoc markdown. -\f[C]pandoc\-citeproc\ \-j\f[] and \f[C]\-y\f[] interconvert these -markup formats as far as possible. +In\-field markup: In BibTeX and BibLaTeX databases, pandoc\-citeproc +parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown; +and in CSL JSON databases, an HTML\-like markup: +.TP +.B \f[C]<i>...</i>\f[] +italics +.RS +.RE +.TP +.B \f[C]<b>...</b>\f[] +bold +.RS +.RE +.TP +.B \f[C]<span\ style="font\-variant:small\-caps;">...</span>\f[] or \f[C]<sc>...</sc>\f[] +small capitals +.RS +.RE +.TP +.B \f[C]<sub>...</sub>\f[] +subscript +.RS +.RE +.TP +.B \f[C]<sup>...</sup>\f[] +superscript +.RS +.RE +.TP +.B \f[C]<span\ class="nocase">...</span>\f[] +prevent a phrase from being capitalized as title case +.RS +.RE +.PP +\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 @@ -3572,15 +3829,14 @@ references: (\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce these from a bibliography file in one of the supported formats.) .PP +Citations and references can be formatted using any style supported by +the Citation Style Language, listed in the Zotero Style Repository. +These files are specified using the \f[C]\-\-csl\f[] option or the +\f[C]csl\f[] metadata field. By default, \f[C]pandoc\-citeproc\f[] will use the Chicago Manual of -Style author\-date format for citations and references. -To use another style, you will need to specify a CSL 1.0 style file in -the \f[C]csl\f[] metadata field. -A repository of CSL styles can be found at -https://github.com/citation\-style\-language/styles. -See also http://zotero.org/styles for easy browsing. -A primer on creating and modifying CSL styles can be found at -http://citationstyles.org/downloads/primer.html. +Style author\-date format. +The CSL project provides further information on finding and editing +styles. .PP Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of \[aq]\@\[aq] + the citation @@ -3593,7 +3849,7 @@ Here are some examples: .IP .nf \f[C] -Blah\ blah\ [see\ \@doe99,\ pp.\ 33\-35;\ also\ \@smith04,\ ch.\ 1]. +Blah\ blah\ [see\ \@doe99,\ pp.\ 33\-35;\ also\ \@smith04,\ chap.\ 1]. Blah\ blah\ [\@doe99,\ pp.\ 33\-35,\ 38\-39\ and\ *passim*]. @@ -3601,6 +3857,25 @@ Blah\ blah\ [\@smith04;\ \@doe99]. \f[] .fi .PP +\f[C]pandoc\-citeproc\f[] detects locator terms in the CSL locale files. +Either abbreviated or unabbreviated forms are accepted. +In the \f[C]en\-US\f[] locale, locator terms can be written in either +singular or plural forms, as \f[C]book\f[], \f[C]bk.\f[]/\f[C]bks.\f[]; +\f[C]chapter\f[], \f[C]chap.\f[]/\f[C]chaps.\f[]; \f[C]column\f[], +\f[C]col.\f[]/\f[C]cols.\f[]; \f[C]figure\f[], +\f[C]fig.\f[]/\f[C]figs.\f[]; \f[C]folio\f[], +\f[C]fol.\f[]/\f[C]fols.\f[]; \f[C]number\f[], +\f[C]no.\f[]/\f[C]nos.\f[]; \f[C]line\f[], \f[C]l.\f[]/\f[C]ll.\f[]; +\f[C]note\f[], \f[C]n.\f[]/\f[C]nn.\f[]; \f[C]opus\f[], +\f[C]op.\f[]/\f[C]opp.\f[]; \f[C]page\f[], \f[C]p.\f[]/\f[C]pp.\f[]; +\f[C]paragraph\f[], \f[C]para.\f[]/\f[C]paras.\f[]; \f[C]part\f[], +\f[C]pt.\f[]/\f[C]pts.\f[]; \f[C]section\f[], +\f[C]sec.\f[]/\f[C]secs.\f[]; \f[C]sub\ verbo\f[], +\f[C]s.v.\f[]/\f[C]s.vv.\f[]; \f[C]verse\f[], \f[C]v.\f[]/\f[C]vv.\f[]; +\f[C]volume\f[], \f[C]vol.\f[]/\f[C]vols.\f[]; \f[C]¶\f[]/\f[C]¶¶\f[]; +\f[C]§\f[]/\f[C]§§\f[]. +If no locator term is used, "page" is assumed. +.PP A minus sign (\f[C]\-\f[]) before the \f[C]\@\f[] will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text: @@ -3656,8 +3931,8 @@ In this example, the document will contain a citation for \f[C]item3\f[] only, but the bibliography will contain entries for \f[C]item1\f[], \f[C]item2\f[], and \f[C]item3\f[]. .PP -For LaTeX or PDF output, you can also use NatBib or BibLaTeX to render -bibliography. +For LaTeX or PDF output, you can also use \f[C]natbib\f[] or +\f[C]biblatex\f[] to render bibliography. In order to do so, specify bibliography files as outlined above, and add \f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] argument to \f[C]pandoc\f[] invocation. @@ -3665,10 +3940,10 @@ Bear in mind that bibliography files have to be in respective format (either BibTeX or BibLaTeX). .SS Non\-pandoc extensions .PP -The following markdown syntax extensions are not enabled by default in +The following Markdown syntax extensions are not enabled by default in pandoc, but may be enabled by adding \f[C]+EXTENSION\f[] to the format name, where \f[C]EXTENSION\f[] is the name of the extension. -Thus, for example, \f[C]markdown+hard_line_breaks\f[] is markdown with +Thus, for example, \f[C]markdown+hard_line_breaks\f[] is Markdown with hard line breaks. .SS Extension: \f[C]lists_without_preceding_blankline\f[] .PP @@ -3685,6 +3960,9 @@ 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]emoji\f[] +.PP +Parses textual emojis like \f[C]:smile:\f[] as Unicode emoticons. .SS Extension: \f[C]tex_math_single_backslash\f[] .PP Causes anything between \f[C]\\(\f[] and \f[C]\\)\f[] to be interpreted @@ -3700,8 +3978,8 @@ interpreted as inline TeX math, and anything between \f[C]\\\\[\f[] and .SS Extension: \f[C]markdown_attribute\f[] .PP By default, pandoc interprets material inside block\-level tags as -markdown. -This extension changes the behavior so that markdown is only parsed +Markdown. +This extension changes the behavior so that Markdown is only parsed inside block\-level tags if the tags have the attribute \f[C]markdown=1\f[]. .SS Extension: \f[C]mmd_title_block\f[] @@ -3728,7 +4006,7 @@ Parses PHP Markdown Extra abbreviation keys, like .IP .nf \f[C] -*[HTML]:\ Hyper\ Text\ Markup\ Language +*[HTML]:\ Hypertext\ Markup\ Language \f[] .fi .PP @@ -3758,7 +4036,8 @@ the header but before any trailing \f[C]#\f[]s in an ATX header). .SS Extension: \f[C]compact_definition_lists\f[] .PP Activates the definition list syntax of pandoc 1.12.x and earlier. -This syntax differs from the one described above in several respects: +This syntax differs from the one described above under Definition lists +in several respects: .IP \[bu] 2 No blank line is required between consecutive items of the definition list. @@ -3771,7 +4050,7 @@ Lazy wrapping of paragraphs is not allowed: the entire definition must be indented four spaces. .SS Markdown variants .PP -In addition to pandoc\[aq]s extended markdown, the following markdown +In addition to pandoc\[aq]s extended Markdown, the following Markdown variants are supported: .TP .B \f[C]markdown_phpextra\f[] (PHP Markdown Extra) @@ -3783,13 +4062,14 @@ variants are supported: .RS .RE .TP -.B \f[C]markdown_github\f[] (GitHub\-flavored Markdown) +.B \f[C]markdown_github\f[] (GitHub\-Flavored Markdown) \f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]tex_math_single_backslash\f[], \f[C]fenced_code_blocks\f[], \f[C]auto_identifiers\f[], \f[C]ascii_identifiers\f[], \f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[], \f[C]intraword_underscores\f[], \f[C]strikeout\f[], -\f[C]hard_line_breaks\f[], \f[C]shortcut_reference_links\f[]. +\f[C]hard_line_breaks\f[], \f[C]emoji\f[], +\f[C]shortcut_reference_links\f[]. .RS .RE .TP @@ -3808,10 +4088,10 @@ variants are supported: \f[C]raw_html\f[] .RS .RE -.SS Extensions with formats other than markdown +.SS Extensions with formats other than Markdown .PP Some of the extensions discussed above can be used with formats other -than markdown: +than Markdown: .IP \[bu] 2 \f[C]auto_identifiers\f[] can be used with \f[C]latex\f[], \f[C]rst\f[], \f[C]mediawiki\f[], and \f[C]textile\f[] input (and is used by default). @@ -3822,13 +4102,13 @@ than markdown: example.) .SH PRODUCING SLIDE SHOWS WITH PANDOC .PP -You can use Pandoc to produce an HTML + javascript slide presentation +You can use pandoc to produce an HTML + javascript slide presentation that can be viewed via a web browser. There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or reveal.js. -You can also produce a PDF slide show using LaTeX beamer. +You can also produce a PDF slide show using LaTeX \f[C]beamer\f[]. .PP -Here\[aq]s the markdown source for a simple slide show, +Here\[aq]s the Markdown source for a simple slide show, \f[C]habits.txt\f[]: .IP .nf @@ -3886,7 +4166,7 @@ CSS files, which are assumed to be available at the relative path \f[C]w3.org\f[] (for Slidy). (These paths can be changed by setting the \f[C]slidy\-url\f[], \f[C]slideous\-url\f[], \f[C]revealjs\-url\f[], or \f[C]s5\-url\f[] -variables; see \f[C]\-\-variable\f[], above.) For DZSlides, the +variables; see Variables for slides, above.) For DZSlides, the (relatively short) javascript and css are included in the file by default. .PP @@ -3993,8 +4273,8 @@ directory. For dzslides, the CSS is included in the HTML file itself, and may be modified there. .PP -For reveal.js, themes can be used by setting the \f[C]theme\f[] -variable, for example: +All reveal.js configuration options can be set through variables. +For example, themes can be used by setting the \f[C]theme\f[] variable: .IP .nf \f[C] @@ -4005,8 +4285,9 @@ variable, for example: Or you can specify a custom stylesheet using the \f[C]\-\-css\f[] option. .PP -To style beamer slides, you can specify a beamer "theme" or "colortheme" -using the \f[C]\-V\f[] option: +To style beamer slides, you can specify a \f[C]theme\f[], +\f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], and +\f[C]outertheme\f[], using the \f[C]\-V\f[] option: .IP .nf \f[C] @@ -4017,7 +4298,7 @@ pandoc\ \-t\ beamer\ habits.txt\ \-V\ theme:Warsaw\ \-o\ habits.pdf Note that header attributes will turn into slide attributes (on a \f[C]<div>\f[] or \f[C]<section>\f[]) in HTML slide formats, allowing you to style individual slides. -In Beamer, the only header attribute that affects slides is the +In beamer, the only header attribute that affects slides is the \f[C]allowframebreaks\f[] class, which sets the \f[C]allowframebreaks\f[] option, causing multiple slides to be created if the content overfills the frame. @@ -4031,14 +4312,14 @@ This is recommended especially for bibliographies: .SS Speaker notes .PP reveal.js has good support for speaker notes. -You can add notes to your markdown document thus: +You can add notes to your Markdown document thus: .IP .nf \f[C] <div\ class="notes"> This\ is\ my\ note. -\-\ It\ can\ contain\ markdown +\-\ It\ can\ contain\ Markdown \-\ like\ this\ list </div> @@ -4049,7 +4330,7 @@ To show the notes window, press \f[C]s\f[] while viewing the presentation. Notes are not yet supported for other slide formats, but the notes will not appear on the slides themselves. -.SS Marking frames "fragile" in beamer +.SS Frame attributes in beamer .PP Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[] option to a frame in beamer (for example, when using the \f[C]minted\f[] @@ -4062,10 +4343,16 @@ introducing the slide: #\ Fragile\ slide\ {.fragile} \f[] .fi -.SH EPUB METADATA +.PP +All of the other frame attributes described in Section 8.1 of the Beamer +User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[], +\f[C]allowframebreaks\f[], \f[C]b\f[], \f[C]c\f[], \f[C]t\f[], +\f[C]environment\f[], \f[C]label\f[], \f[C]plain\f[], \f[C]shrink\f[]. +.SH CREATING EPUBS WITH PANDOC +.SS EPUB Metadata .PP EPUB metadata may be specified using the \f[C]\-\-epub\-metadata\f[] -option, but if the source document is markdown, it is better to use a +option, but if the source document is Markdown, it is better to use a YAML metadata block. Here is an example: .IP @@ -4116,7 +4403,7 @@ Valid values for \f[C]type\f[] are \f[C]main\f[], \f[C]subtitle\f[], .B \f[C]creator\f[] Either a string value, or an object with fields \f[C]role\f[], \f[C]file\-as\f[], and \f[C]text\f[], or a list of such objects. -Valid values for \f[C]role\f[] are marc relators, but pandoc will +Valid values for \f[C]role\f[] are MARC relators, but pandoc will attempt to translate the human\-readable versions (like "author" and "editor") to the appropriate marc relators. .RS @@ -4134,8 +4421,8 @@ common date formats. .RS .RE .TP -.B \f[C]language\f[] -A string value in RFC5646 format. +.B \f[C]lang\f[] (or legacy: \f[C]language\f[]) +A string value in BCP 47 format. Pandoc will default to the local language if nothing is specified. .RS .RE @@ -4187,9 +4474,29 @@ A string value (path to CSS stylesheet). .TP .B \f[C]page\-progression\-direction\f[] Either \f[C]ltr\f[] or \f[C]rtl\f[]. -Specifies the \f[C]page\-progression\-direction\f[] spine attribute. +Specifies the \f[C]page\-progression\-direction\f[] attribute for the +\f[C]spine\f[] element. .RS .RE +.SS Linked media +.PP +By default, pandoc will download linked media (including audio and +video) and include it in the EPUB container, yielding a completely +self\-contained EPUB. +If you want to link to external media resources instead, use raw HTML in +your source and add \f[C]data\-external="1"\f[] to the tag with the +\f[C]src\f[] attribute. +For example: +.IP +.nf +\f[C] +<audio\ controls="1"> +\ \ <source\ src="http://example.com/music/toccata.mp3" +\ \ \ \ \ \ \ \ \ \ data\-external="1"\ type="audio/mpeg"> +\ \ </source> +</audio> +\f[] +.fi .SH LITERATE HASKELL SUPPORT .PP If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to an @@ -4199,17 +4506,19 @@ output; \f[C]beamer\f[], \f[C]html\f[] or \f[C]html5\f[] for output only), pandoc will treat the document as literate Haskell source. This means that .IP \[bu] 2 -In markdown input, "bird track" sections will be parsed as Haskell code +In Markdown input, "bird track" sections will be parsed as Haskell code rather than block quotations. Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also be treated as Haskell code. +For ATX\-style headers the character \[aq]=\[aq] will be used instead of +\[aq]#\[aq]. .IP \[bu] 2 -In markdown output, code blocks with classes \f[C]haskell\f[] and +In Markdown output, code blocks with classes \f[C]haskell\f[] and \f[C]literate\f[] will be rendered using bird tracks, and block quotations will be indented one space, so they will not be treated as Haskell code. In addition, headers will be rendered setext\-style (with underlines) -rather than atx\-style (with \[aq]#\[aq] characters). +rather than ATX\-style (with \[aq]#\[aq] characters). (This is because ghc treats \[aq]#\[aq] characters in column 1 as introducing line numbers.) .IP \[bu] 2 @@ -4236,7 +4545,7 @@ pandoc\ \-f\ markdown+lhs\ \-t\ html \f[] .fi .PP -reads literate Haskell source formatted with markdown conventions and +reads literate Haskell source formatted with Markdown conventions and writes ordinary HTML (without bird tracks). .IP .nf @@ -4251,10 +4560,8 @@ and pasted as literate Haskell source. .PP Pandoc will automatically highlight syntax in fenced code blocks that are marked with a language name. -(See [Extension: \f[C]inline_code_attributes\f[]] and [Extension: -\f[C]fenced_code_attributes\f[]], above.) The Haskell library -highlighting\-kate is used for highlighting, which works in HTML, Docx, -and LaTeX/PDF output. +The Haskell library highlighting\-kate is used for highlighting, which +works in HTML, Docx, and LaTeX/PDF output. The color scheme can be selected using the \f[C]\-\-highlight\-style\f[] option. The default color scheme is \f[C]pygments\f[], which imitates the @@ -4300,9 +4607,10 @@ This software carries no warranty of any kind. .PP Contributors include Aaron Wolen, Albert Krewinkel, Alexander Kondratskiy, Alexander Sulfrian, Alexander V Vershilov, Alfred -Wechselberger, Andreas Lööw, Andrew Dunning, Antoine Latter, Arlo -O\[aq]Keeffe, Artyom Kazak, Ben Gamari, Beni Cherniavsky\-Paskin, Bjorn -Buckwalter, Bradley Kuhn, Brent Yorgey, Bryan O\[aq]Sullivan, B. +Wechselberger, Andreas Lööw, Andrew Dunning, Antoine Latter, Arata +Mizuki, Arlo O\[aq]Keeffe, Artyom Kazak, Ben Gamari, Beni +Cherniavsky\-Paskin, Bjorn Buckwalter, Bradley Kuhn, Brent Yorgey, Bryan +O\[aq]Sullivan, B. Scott Michel, Caleb McDaniel, Calvin Beck, Christoffer Ackelman, Christoffer Sawicki, Clare Macrae, Clint Adams, Conal Elliott, Craig S. Bosma, Daniel Bergey, Daniel T. @@ -4312,7 +4620,7 @@ Calvert, Eric Kow, Eric Seidel, Florian Eitel, François Gannaz, Freiric Barral, Fyodor Sheremetyev, Gabor Pali, Gavin Beatty, Greg Maslov, Grégory Bataille, Greg Rundlett, gwern, Gwern Branwen, Hans\-Peter Deifel, Henry de Valence, Ilya V. -Portnov, infinity0x, Jaime Marquínez Ferrándiz, James Aspnes, Jamie F. +Portnov, infinity0x, Jaime Marquínez Ferrándiz, James Aspnes, Jamie F. Olson, Jan Larres, Jason Ronallo, Jeff Arnold, Jeff Runningen, Jens Petersen, Jérémy Bobbio, Jesse Rosenthal, J. Lewis Muir, Joe Hillenbrand, John MacFarlane, Jonas Smedegaard, Jonathan |