diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/man1/markdown2pdf.1 | 170 | ||||
| -rw-r--r-- | man/man1/markdown2pdf.1.md | 120 | ||||
| -rw-r--r-- | man/man1/pandoc.1 | 827 | ||||
| -rw-r--r-- | man/man5/pandoc_markdown.5 | 120 |
4 files changed, 643 insertions, 594 deletions
diff --git a/man/man1/markdown2pdf.1 b/man/man1/markdown2pdf.1 deleted file mode 100644 index 20c566c8d..000000000 --- a/man/man1/markdown2pdf.1 +++ /dev/null @@ -1,170 +0,0 @@ -.TH MARKDOWN2PDF 1 "January 29, 2011" "Pandoc User Manuals" -.SH NAME -.PP -markdown2pdf - converts markdown-formatted text to PDF, using pdflatex -.SH SYNOPSIS -.PP -markdown2pdf [\f[I]options\f[]] [\f[I]input-file\f[]]... -.SH DESCRIPTION -.PP -\f[C]markdown2pdf\f[] converts \f[I]input-file\f[] (or text from -standard input) from markdown-formatted plain text to PDF, using -\f[C]pandoc\f[] and \f[C]pdflatex\f[]. -If no output filename is specified (using the \f[C]-o\f[] option), the -name of the output file is derived from the input file; thus, for -example, if the input file is \f[I]hello.txt\f[], the output file will -be \f[I]hello.pdf\f[]. -If the input is read from STDIN and no output filename is specified, the -output file will be named \f[I]stdin.pdf\f[]. -If multiple input files are specified, they will be concatenated before -conversion, and the name of the output file will be derived from the -first input file. -.PP -Input is assumed to be in the UTF-8 character encoding. -If your local character encoding is not UTF-8, you should pipe input -through \f[C]iconv\f[]: -.IP -.nf -\f[C] -iconv\ -t\ utf-8\ input.txt\ |\ markdown2pdf -\f[] -.fi -.PP -\f[C]markdown2pdf\f[] assumes that the \f[C]unicode\f[], \f[C]array\f[], -\f[C]fancyvrb\f[], \f[C]graphicx\f[], and \f[C]ulem\f[] packages are in -latex\[aq]s search path. -If these packages are not included in your latex setup, they can be -obtained from \f[C]http://ctan.org\f[]. -.SH OPTIONS -.TP -.B -o \f[I]FILE\f[], --output=\f[I]FILE\f[] -Write output to \f[I]FILE\f[]. -.RS -.RE -.TP -.B --strict -Use strict markdown syntax, with no extensions or variants. -.RS -.RE -.TP -.B -N, --number-sections -Number section headings in LaTeX output. -(Default is not to number them.) -.RS -.RE -.TP -.B --listings -Use listings package for LaTeX code blocks -.RS -.RE -.TP -.B --template=\f[I]FILE\f[] -Use \f[I]FILE\f[] as a custom template for the generated document. -Implies \f[C]-s\f[]. -See the section TEMPLATES in \f[C]pandoc\f[](1) for information about -template syntax. -Use \f[C]pandoc\ -D\ latex\f[] to print the default LaTeX template. -.RS -.RE -.TP -.B -V KEY=VAL, --variable=\f[I]KEY:VAL\f[] -Set the template variable KEY to the value VAL when rendering the -document in standalone mode. -Use this to set the font size when using the default LaTeX template: -\f[C]-V\ fontsize=12pt\f[]. -.RS -.RE -.TP -.B -H \f[I]FILE\f[], --include-in-header=\f[I]FILE\f[] -Include (LaTeX) contents of \f[I]FILE\f[] at the end of the header. -Implies \f[C]-s\f[]. -.RS -.RE -.TP -.B -B \f[I]FILE\f[], --include-before-body=\f[I]FILE\f[] -Include (LaTeX) contents of \f[I]FILE\f[] at the beginning of the -document body. -.RS -.RE -.TP -.B -A \f[I]FILE\f[], --include-after-body=\f[I]FILE\f[] -Include (LaTeX) contents of \f[I]FILE\f[] at the end of the document -body. -.RS -.RE -.TP -.B --bibliography=\f[I]FILE\f[] -Specify bibliography database to be used in resolving citations. -The database type will be determined from the extension of -\f[I]FILE\f[], which may be \f[C].xml\f[] (MODS format), \f[C].bib\f[] -(BibTeX format), or \f[C].json\f[] (citeproc JSON). -.RS -.RE -.TP -.B --csl=\f[I]FILE\f[] -Specify CSL style to be used in formatting citations and the -bibliography. -If \f[I]FILE\f[] is not found, pandoc will look for it in -.RS -.IP -.nf -\f[C] -$HOME/.csl -\f[] -.fi -.PP -in unix and -.IP -.nf -\f[C] -C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\csl -\f[] -.fi -.PP -in Windows. -If the \f[C]--csl\f[] option is not specified, pandoc will use a default -style: either \f[C]default.csl\f[] in the user data directory (see -\f[C]--data-dir\f[]), or, if that is not present, the Chicago -author-date style. -.RE -.TP -.B --data-dir\f[I]=DIRECTORY\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: -.RS -.IP -.nf -\f[C] -$HOME/.pandoc -\f[] -.fi -.PP -in unix and -.IP -.nf -\f[C] -C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc -\f[] -.fi -.PP -in Windows. -A \f[C]reference.odt\f[], \f[C]epub.css\f[], \f[C]templates\f[] -directory, or \f[C]s5\f[] directory placed in this directory will -override pandoc\[aq]s normal defaults. -.RE -.TP -.B --xetex -Use xelatex instead of pdflatex to create the PDF. -.RS -.RE -.TP -.B --luatex -Use lualatex instead of pdflatex to create the PDF. -.RS -.RE -.SH SEE ALSO -.PP -\f[C]pandoc\f[](1), \f[C]pdflatex\f[](1) -.SH AUTHORS -John MacFarlane, Paulo Tanimoto, and Recai Oktas. diff --git a/man/man1/markdown2pdf.1.md b/man/man1/markdown2pdf.1.md deleted file mode 100644 index 8b8da6880..000000000 --- a/man/man1/markdown2pdf.1.md +++ /dev/null @@ -1,120 +0,0 @@ -% MARKDOWN2PDF(1) Pandoc User Manuals -% John MacFarlane, Paulo Tanimoto, and Recai Oktas -% January 29, 2011 - -# NAME - -markdown2pdf - converts markdown-formatted text to PDF, using pdflatex - -# SYNOPSIS - -markdown2pdf [*options*] [*input-file*]... - -# DESCRIPTION - -`markdown2pdf` converts *input-file* (or text from standard -input) from markdown-formatted plain text to PDF, using `pandoc` -and `pdflatex`. If no output filename is specified (using the `-o` -option), the name of the output file is derived from the input file; -thus, for example, if the input file is *hello.txt*, the output file -will be *hello.pdf*. If the input is read from STDIN and no output -filename is specified, the output file will be named *stdin.pdf*. If -multiple input files are specified, they will be concatenated before -conversion, and the name of the output file will be derived from the -first input file. - -Input is assumed to be in the UTF-8 character encoding. If your -local character encoding is not UTF-8, you should pipe input -through `iconv`: - - iconv -t utf-8 input.txt | markdown2pdf - -`markdown2pdf` assumes that the `unicode`, `array`, `fancyvrb`, -`graphicx`, and `ulem` packages are in latex's search path. If these -packages are not included in your latex setup, they can be obtained from -<http://ctan.org>. - -# OPTIONS - --o *FILE*, \--output=*FILE* -: Write output to *FILE*. - -\--strict -: Use strict markdown syntax, with no extensions or variants. - --N, \--number-sections -: Number section headings in LaTeX output. (Default is not to number them.) - -\--listings -: Use listings package for LaTeX code blocks - -\--template=*FILE* -: Use *FILE* as a custom template for the generated document. Implies - `-s`. See the section TEMPLATES in `pandoc`(1) for information about - template syntax. Use `pandoc -D latex` to print the default LaTeX - template. - --V KEY=VAL, \--variable=*KEY:VAL* -: Set the template variable KEY to the value VAL when rendering the - document in standalone mode. Use this to set the font size when - using the default LaTeX template: `-V fontsize=12pt`. - --H *FILE*, \--include-in-header=*FILE* -: Include (LaTeX) contents of *FILE* at the end of the header. Implies - `-s`. - --B *FILE*, \--include-before-body=*FILE* -: Include (LaTeX) contents of *FILE* at the beginning of the document body. - --A *FILE*, \--include-after-body=*FILE* -: Include (LaTeX) contents of *FILE* at the end of the document body. - -\--bibliography=*FILE* -: Specify bibliography database to be used in resolving - citations. The database type will be determined from the - extension of *FILE*, which may be `.xml` (MODS format), - `.bib` (BibTeX format), or `.json` (citeproc JSON). - -\--csl=*FILE* -: Specify [CSL] style to be used in formatting citations and - the bibliography. If *FILE* is not found, pandoc will look - for it in - - $HOME/.csl - - in unix and - - C:\Documents And Settings\USERNAME\Application Data\csl - - in Windows. If the `--csl` option is not specified, pandoc - will use a default style: either `default.csl` in the - user data directory (see `--data-dir`), or, if that is - not present, the Chicago author-date style. - -\--data-dir*=DIRECTORY* -: 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: - - $HOME/.pandoc - - in unix and - - C:\Documents And Settings\USERNAME\Application Data\pandoc - - in Windows. A `reference.odt`, `epub.css`, `templates` directory, - or `s5` directory placed in this directory will override pandoc's - normal defaults. - -\--xetex -: Use xelatex instead of pdflatex to create the PDF. - -\--luatex -: Use lualatex instead of pdflatex to create the PDF. - -# SEE ALSO - -`pandoc`(1), `pdflatex`(1) - -[CSL]: CitationStyles.org - diff --git a/man/man1/pandoc.1 b/man/man1/pandoc.1 index 702e684ed..d7f3227a3 100644 --- a/man/man1/pandoc.1 +++ b/man/man1/pandoc.1 @@ -1,4 +1,4 @@ -.TH PANDOC 1 "July 30, 2011" "Pandoc" +.TH PANDOC 1 "January 27, 2012" "Pandoc" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -10,9 +10,11 @@ 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 and (subsets of) Textile, reStructuredText, HTML, and LaTeX; and it can write plain text, markdown, reStructuredText, -HTML, LaTeX, ConTeXt, RTF, DocBook XML, OpenDocument XML, ODT, GNU -Texinfo, MediaWiki markup, EPUB, Textile, groff man pages, Emacs -Org-Mode, and Slidy or S5 HTML slide shows. +XHTML, HTML 5, LaTeX (including beamer slide shows), ConTeXt, RTF, +DocBook XML, OpenDocument XML, ODT, Word docx, GNU Texinfo, MediaWiki +markup, EPUB, Textile, groff man pages, Emacs Org-Mode, AsciiDoc, and +Slidy, DZSlides, 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, tables, flexible ordered lists, definition lists, delimited code blocks, @@ -29,15 +31,15 @@ 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. -.SS Using Pandoc +.SS Using \f[C]pandoc\f[] .PP If no \f[I]input-file\f[] is 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 -\f[I]stdout\f[] is disabled for the \f[C]odt\f[] and \f[C]epub\f[] -output formats). +\f[I]stdout\f[] is disabled for the \f[C]odt\f[], \f[C]docx\f[], and +\f[C]epub\f[] output formats). For output to a file, use the \f[C]-o\f[] option: .IP .nf @@ -116,7 +118,45 @@ output through \f[C]iconv\f[]: iconv\ -t\ utf-8\ input.txt\ |\ pandoc\ |\ iconv\ -f\ utf-8 \f[] .fi +.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[] +extension. +Pandoc will create a latex file and use pdflatex (or another engine, see +\f[C]--latex-engine\f[]) to convert it to PDF: +.IP +.nf +\f[C] +pandoc\ test.txt\ -o\ test.pdf +\f[] +.fi +.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]enumerate\f[], \f[C]ctable\f[], \f[C]url\f[], \f[C]graphicx\f[], +\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). +.SS \f[C]hsmarkdown\f[] +.PP +A user who wants a drop-in replacement for \f[C]Markdown.pl\f[] may +create a symbolic link to the \f[C]pandoc\f[] executable called +\f[C]hsmarkdown\f[]. +When invoked under the name \f[C]hsmarkdown\f[], \f[C]pandoc\f[] will +behave as if the \f[C]--strict\f[] flag had been selected, and no +command-line options will be recognized. +However, this approach does not work under Cygwin, due to problems with +its simulation of symbolic links. .SH OPTIONS +.SS General options .TP .B \f[C]-f\f[] \f[I]FORMAT\f[], \f[C]-r\f[] \f[I]FORMAT\f[], \f[C]--from=\f[]\f[I]FORMAT\f[], \f[C]--read=\f[]\f[I]FORMAT\f[] @@ -137,46 +177,72 @@ 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[] (markdown), \f[C]rst\f[] (reStructuredText), -\f[C]html\f[] (HTML), \f[C]latex\f[] (LaTeX), \f[C]context\f[] +\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]textile\f[] (Textile), \f[C]org\f[] (Emacs Org-Mode), \f[C]texinfo\f[] (GNU Texinfo), \f[C]docbook\f[] (DocBook XML), \f[C]opendocument\f[] (OpenDocument XML), \f[C]odt\f[] (OpenOffice text -document), \f[C]epub\f[] (EPUB book), \f[C]slidy\f[] (Slidy HTML and -javascript slide show), \f[C]s5\f[] (S5 HTML and javascript slide show), -or \f[C]rtf\f[] (rich text format). +document), \f[C]docx\f[] (Word docx), \f[C]epub\f[] (EPUB book), +\f[C]asciidoc\f[] (AsciiDoc), \f[C]slidy\f[] (Slidy HTML and javascript +slide show), \f[C]dzslides\f[] (HTML5 + javascript slide show), +\f[C]s5\f[] (S5 HTML and javascript slide show), or \f[C]rtf\f[] (rich +text format). Note that \f[C]odt\f[] and \f[C]epub\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. 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 output will be rendered as -literate Haskell source: see Literate Haskell support, below. -.RS -.RE -.TP -.B \f[C]-s\f[], \f[C]--standalone\f[] -Produce output with an appropriate header and footer (e.g. -a standalone HTML, LaTeX, or RTF file, not a fragment). +\f[C]latex\f[], \f[C]html\f[], or \f[C]html5\f[], the output will be +rendered as literate Haskell source: see Literate Haskell support, +below. .RS .RE .TP .B \f[C]-o\f[] \f[I]FILE\f[], \f[C]--output=\f[]\f[I]FILE\f[] Write output to \f[I]FILE\f[] instead of \f[I]stdout\f[]. If \f[I]FILE\f[] is \f[C]-\f[], output will go to \f[I]stdout\f[]. -(Exception: if the output format is \f[C]odt\f[] or \f[C]epub\f[], -output to stdout is disabled.) +(Exception: if the output format is \f[C]odt\f[], \f[C]docx\f[], or +\f[C]epub\f[], output to stdout is disabled.) .RS .RE .TP -.B \f[C]-p\f[], \f[C]--preserve-tabs\f[] -Preserve tabs instead of converting them to spaces (the default). +.B \f[C]--data-dir=\f[]\f[I]DIRECTORY\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: +.RS +.IP +.nf +\f[C] +$HOME/.pandoc +\f[] +.fi +.PP +in unix and +.IP +.nf +\f[C] +C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc +\f[] +.fi +.PP +in Windows. +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[], or \f[C]s5\f[] +directory placed in this directory will override pandoc\[aq]s normal +defaults. +.RE +.TP +.B \f[C]-v\f[], \f[C]--version\f[] +Print version. .RS .RE .TP -.B \f[C]--tab-stop=\f[]\f[I]NUMBER\f[] -Specify the number of spaces per tab (default is 4). +.B \f[C]-h\f[], \f[C]--help\f[] +Show usage message. .RS .RE +.SS Reader options .TP .B \f[C]--strict\f[] Use strict markdown syntax, with no pandoc extensions or variants. @@ -186,27 +252,13 @@ definition lists or strikeout text) will be parsed as raw HTML. .RS .RE .TP -.B \f[C]--normalize\f[] -Normalize the document after reading: merge adjacent \f[C]Str\f[] or -\f[C]Emph\f[] elements, for example, and remove repeated -\f[C]Space\f[]s. -.RS -.RE -.TP -.B \f[C]--reference-links\f[] -Use reference-style links, rather than inline links, in writing markdown -or reStructuredText. -By default inline links are used. -.RS -.RE -.TP .B \f[C]-R\f[], \f[C]--parse-raw\f[] 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, and -S5 output; raw LaTeX can be printed in markdown, reStructuredText, -LaTeX, and ConTeXt output. +Raw HTML can be printed in markdown, reStructuredText, HTML, Slidy, +DZSlides, and S5 output; raw LaTeX can be printed 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 @@ -216,8 +268,8 @@ LaTeX environments. .TP .B \f[C]-S\f[], \f[C]--smart\f[] Produce typographically correct output, converting straight quotes to -curly quotes, \f[C]---\f[] and \f[C]--\f[] to dashes, ande \f[C]...\f[] -to ellipses. +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[] or \f[C]textile\f[]. @@ -226,108 +278,79 @@ or the output format is \f[C]latex\f[] or \f[C]context\f[].) .RS .RE .TP -.B \f[C]-5\f[], \f[C]--html5\f[] -Produce HTML5 instead of HTML4. -This option has no effect for writers other than \f[C]html\f[]. -.RS -.RE -.TP -.B \f[C]-m\f[] [\f[I]URL\f[]], \f[C]--latexmathml\f[][=\f[I]URL\f[]] -Use the LaTeXMathML script to display embedded TeX math in HTML output. -To insert a link to a local copy of the \f[C]LaTeXMathML.js\f[] script, -provide a \f[I]URL\f[]. -If no \f[I]URL\f[] is provided, the contents of the script will be -inserted directly into the HTML header, preserving portability at the -price of efficiency. -If you plan to use math on several pages, it is much better to link to a -copy of the script, so it can be cached. -.RS -.RE -.TP -.B \f[C]--mathml\f[][=\f[I]URL\f[]] -Convert TeX math to MathML. -In standalone mode, a small javascript (or a link to such a script if a -\f[I]URL\f[] is supplied) will be inserted that allows the MathML to be -viewed on some browsers. -.RS -.RE -.TP -.B \f[C]--jsmath\f[][=\f[I]URL\f[]] -Use jsMath to display embedded TeX math in HTML output. -The \f[I]URL\f[] should point to the jsMath load script (e.g. -\f[C]jsMath/easy/load.js\f[]); if provided, it will be linked to in the -header of standalone HTML documents. -If a \f[I]URL\f[] is not provided, no link to the jsMath load script -will be inserted; it is then up to the author to provide such a link in -the HTML template. -.RS -.RE -.TP -.B \f[C]--mathjax\f[][=\f[I]URL\f[]] -Use MathJax to display embedded TeX math in HTML output. -The \f[I]URL\f[] should point to the \f[C]MathJax.js\f[] load script. -If a \f[I]URL\f[] is not provided, a link to the MathJax CDN will be -inserted. +.B \f[C]--old-dashes\f[] +Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: +\f[C]-\f[] before a numeral is an en-dash, and \f[C]--\f[] is an +em-dash. +This option is selected automatically for \f[C]textile\f[] input. .RS .RE .TP -.B \f[C]--gladtex\f[] -Enclose TeX math in \f[C]<eq>\f[] tags in HTML output. -These can then be processed by gladTeX to produce links to images of the -typeset formulas. +.B \f[C]--base-header-level=\f[]\f[I]NUMBER\f[] +Specify the base level for headers (defaults to 1). .RS .RE .TP -.B \f[C]--mimetex\f[][=\f[I]URL\f[]] -Render TeX math using the mimeTeX CGI script. -If \f[I]URL\f[] is not specified, it is assumed that the script is at -\f[C]/cgi-bin/mimetex.cgi\f[]. +.B \f[C]--indented-code-classes=\f[]\f[I]CLASSES\f[] +Specify classes to use for indented code blocks--for example, +\f[C]perl,numberLines\f[] or \f[C]haskell\f[]. +Multiple classes may be separated by spaces or commas. .RS .RE .TP -.B \f[C]--webtex\f[][=\f[I]URL\f[]] -Render TeX formulas using an external script that converts TeX formulas -to images. -The formula will be concatenated with the URL provided. -If \f[I]URL\f[] is not specified, the Google Chart API will be used. +.B \f[C]--normalize\f[] +Normalize the document after reading: merge adjacent \f[C]Str\f[] or +\f[C]Emph\f[] elements, for example, and remove repeated +\f[C]Space\f[]s. .RS .RE .TP -.B \f[C]-i\f[], \f[C]--incremental\f[] -Make list items in Slidy or S5 display incrementally (one by one). -The default is for lists to be displayed all at once. +.B \f[C]-p\f[], \f[C]--preserve-tabs\f[] +Preserve tabs instead of converting them to spaces (the default). .RS .RE .TP -.B \f[C]--offline\f[] -Include all the CSS and javascript needed for a Slidy or S5 slide show -in the output, so that the slide show will work even when no internet -connection is available. +.B \f[C]--tab-stop=\f[]\f[I]NUMBER\f[] +Specify the number of spaces per tab (default is 4). .RS .RE +.SS General writer options .TP -.B \f[C]--chapters\f[] -Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook -output. +.B \f[C]-s\f[], \f[C]--standalone\f[] +Produce output with an appropriate header and footer (e.g. +a standalone HTML, LaTeX, or RTF file, not a fragment). +This option is set automatically for \f[C]pdf\f[], \f[C]epub\f[], +\f[C]docx\f[], and \f[C]odt\f[] output. .RS .RE .TP -.B \f[C]-N\f[], \f[C]--number-sections\f[] -Number section headings in LaTeX, ConTeXt, or HTML output. -By default, sections are not numbered. +.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. +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. +If the template is not found, pandoc will search for it in the user data +directory (see \f[C]--data-dir\f[]). +If this option is not used, a default template appropriate for the +output format will be used (see \f[C]-D/--print-default-template\f[]). .RS .RE .TP -.B \f[C]--listings\f[] -Use listings package for LaTeX code blocks +.B \f[C]-V\f[] \f[I]KEY=VAL\f[], \f[C]--variable=\f[]\f[I]KEY:VAL\f[] +Set the template variable \f[I]KEY\f[] to the value \f[I]VAL\f[] when +rendering the document in standalone mode. +This is generally only useful when the \f[C]--template\f[] option is +used to specify a custom template, since pandoc automatically sets the +variables used in the default templates. .RS .RE .TP -.B \f[C]--section-divs\f[] -Wrap sections in \f[C]<div>\f[] tags (or \f[C]<section>\f[] tags in -HTML5), and attach identifiers to the enclosing \f[C]<div>\f[] (or -\f[C]<section>\f[]) rather than the header itself. -See Section identifiers, below. +.B \f[C]-D\f[] \f[I]FORMAT\f[], +\f[C]--print-default-template=\f[]\f[I]FORMAT\f[] +Print the default template for an output \f[I]FORMAT\f[]. +(See \f[C]-t\f[] for a list of possible \f[I]FORMAT\f[]s.) .RS .RE .TP @@ -342,40 +365,6 @@ Specify length of lines in characters (for text wrapping). .RS .RE .TP -.B \f[C]--ascii\f[] -Use only ascii characters in output. -Currently supported only for HTML output (which uses numerical entities -instead of UTF-8 when this option is selected). -.RS -.RE -.TP -.B \f[C]--email-obfuscation=\f[]\f[I]none|javascript|references\f[] -Specify a method for obfuscating \f[C]mailto:\f[] links in HTML -documents. -\f[I]none\f[] leaves \f[C]mailto:\f[] links as they are. -\f[I]javascript\f[] obfuscates them using javascript. -\f[I]references\f[] obfuscates them by printing their letters as decimal -or hexadecimal character references. -If \f[C]--strict\f[] is specified, \f[I]references\f[] is used -regardless of the presence of this option. -.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 output. -This is useful for preventing duplicate identifiers when generating -fragments to be included in other pages. -.RS -.RE -.TP -.B \f[C]--indented-code-classes=\f[]\f[I]CLASSES\f[] -Specify classes to use for indented code blocks--for example, -\f[C]perl,numberLines\f[] or \f[C]haskell\f[]. -Multiple classes may be separated by spaces or commas. -.RS -.RE -.TP .B \f[C]--toc\f[], \f[C]--table-of-contents\f[] Include an automatically generated table of contents (or, in the case of \f[C]latex\f[], \f[C]context\f[], and \f[C]rst\f[], an instruction to @@ -385,36 +374,17 @@ This option has no effect on \f[C]man\f[], \f[C]docbook\f[], .RS .RE .TP -.B \f[C]--base-header-level=\f[]\f[I]NUMBER\f[] -Specify the base level for headers (defaults to 1). +.B \f[C]--no-highlight\f[] +Disables syntax highlighting for code blocks and inlines, even when a +language attribute is given. .RS .RE .TP -.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. -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. -If the template is not found, pandoc will search for it in the user data -directory (see \f[C]--data-dir\f[]). -If this option is not used, a default template appropriate for the -output format will be used (see \f[C]-D/--print-default-template\f[]). -.RS -.RE -.TP -.B \f[C]-V\f[] \f[I]KEY=VAL\f[], \f[C]--variable=\f[]\f[I]KEY:VAL\f[] -Set the template variable \f[I]KEY\f[] to the value \f[I]VAL\f[] when -rendering the document in standalone mode. -This is generally only useful when the \f[C]--template\f[] option is -used to specify a custom template, since pandoc automatically sets the -variables used in the default templates. -.RS -.RE -.TP -.B \f[C]-c\f[] \f[I]URL\f[], \f[C]--css=\f[]\f[I]URL\f[] -Link to a CSS style sheet. +.B \f[C]--highlight-style\f[]=\f[I]STYLE\f[] +Specifies the coloring style to be used in highlighted source code. +Options are \f[C]pygments\f[] (the default), \f[C]kate\f[], +\f[C]monochrome\f[], \f[C]espresso\f[], \f[C]haddock\f[], and +\f[C]tango\f[]. .RS .RE .TP @@ -453,6 +423,137 @@ They will be included in the order specified. Implies \f[C]--standalone\f[]. .RS .RE +.SS Options affecting specific writers +.TP +.B \f[C]--self-contained\f[] +Produce a standalone HTML file with no external dependencies, using +\f[C]data:\f[] URIs to incorporate the contents of linked scripts, +stylesheets, images, and videos. +The resulting file should be "self-contained," in the sense that it +needs no external files and no net access to be displayed properly by a +browser. +This option works only with HTML output formats, including +\f[C]html\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[], +\f[C]s5\f[], \f[C]slidy\f[], and \f[C]dzslides\f[]. +Scripts, images, and stylesheets at absolute URLs will be downloaded; +those at relative URLs will be sought first relative to the working +directory, then relative to the user data directory (see +\f[C]--data-dir\f[]), and finally relative to pandoc\[aq]s default data +directory. +.RS +.RE +.TP +.B \f[C]--offline\f[] +Deprecated synonym for \f[C]--self-contained\f[]. +.RS +.RE +.TP +.B \f[C]-5\f[], \f[C]--html5\f[] +Produce HTML5 instead of HTML4. +This option has no effect for writers other than \f[C]html\f[]. +(\f[I]Deprecated:\f[] Use the \f[C]html5\f[] output format instead.) +.RS +.RE +.TP +.B \f[C]--ascii\f[] +Use only ascii characters in output. +Currently supported only for HTML output (which uses numerical entities +instead of UTF-8 when this option is selected). +.RS +.RE +.TP +.B \f[C]--reference-links\f[] +Use reference-style links, rather than inline links, in writing markdown +or reStructuredText. +By default inline links are used. +.RS +.RE +.TP +.B \f[C]--atx-headers\f[] +Use ATX style headers in markdown output. +The default is to use setext-style headers for levels 1-2, and then ATX +headers. +.RS +.RE +.TP +.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. +If \f[C]--beamer\f[] is used, top-level headers will become +\f[C]\\part{..}\f[]. +.RS +.RE +.TP +.B \f[C]-N\f[], \f[C]--number-sections\f[] +Number section headings in LaTeX, ConTeXt, or HTML output. +By default, sections are not numbered. +.RS +.RE +.TP +.B \f[C]--listings\f[] +Use listings package for LaTeX code blocks +.RS +.RE +.TP +.B \f[C]-i\f[], \f[C]--incremental\f[] +Make list items in slide shows display incrementally (one by one). +The default is for lists to be displayed all at once. +.RS +.RE +.TP +.B \f[C]--slide-level\f[]=\f[I]NUMBER\f[] +Specifies that headers with the specified level create slides (for +\f[C]beamer\f[], \f[C]s5\f[], \f[C]slidy\f[], \f[C]dzslides\f[]). +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. +.RS +.RE +.TP +.B \f[C]--section-divs\f[] +Wrap sections in \f[C]<div>\f[] tags (or \f[C]<section>\f[] tags in +HTML5), and attach identifiers to the enclosing \f[C]<div>\f[] (or +\f[C]<section>\f[]) rather than the header itself. +See Section identifiers, below. +.RS +.RE +.TP +.B \f[C]--email-obfuscation=\f[]\f[I]none|javascript|references\f[] +Specify a method for obfuscating \f[C]mailto:\f[] links in HTML +documents. +\f[I]none\f[] leaves \f[C]mailto:\f[] links as they are. +\f[I]javascript\f[] obfuscates them using javascript. +\f[I]references\f[] obfuscates them by printing their letters as decimal +or hexadecimal character references. +If \f[C]--strict\f[] is specified, \f[I]references\f[] is used +regardless of the presence of this option. +.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 output. +This is useful for preventing duplicate identifiers when generating +fragments to be included in other pages. +.RS +.RE +.TP +.B \f[C]-T\f[] \f[I]STRING\f[], \f[C]--title-prefix=\f[]\f[I]STRING\f[] +Specify \f[I]STRING\f[] as a prefix at the beginning of the title that +appears in the HTML header (but not in the title as it appears at the +beginning of the HTML body). +Implies \f[C]--standalone\f[]. +.RS +.RE +.TP +.B \f[C]-c\f[] \f[I]URL\f[], \f[C]--css=\f[]\f[I]URL\f[] +Link to a CSS style sheet. +.RS +.RE .TP .B \f[C]--reference-odt=\f[]\f[I]FILE\f[] Use the specified file as a style reference in producing an ODT. @@ -467,11 +568,23 @@ If this is not found either, sensible defaults will be used. .RS .RE .TP +.B \f[C]--reference-docx=\f[]\f[I]FILE\f[] +Use the specified file as a style reference in producing a docx file. +For best results, the reference docx should be a modified version of a +docx file produced using pandoc. +The contents of the reference docx are ignored, but its stylesheets are +used in the new docx. +If no reference docx is specified on the command line, pandoc will look +for a file \f[C]reference.docx\f[] in the user data directory (see +\f[C]--data-dir\f[]). +If this is not found either, sensible defaults will be used. +.RS +.RE +.TP .B \f[C]--epub-stylesheet=\f[]\f[I]FILE\f[] Use the specified CSS file to style the EPUB. If no stylesheet is specified, pandoc will look for a file -\f[C]epub.css\f[] in the user data directory (see \f[C]--data-dir\f[], -below). +\f[C]epub.css\f[] in the user data directory (see \f[C]--data-dir\f[]). If it is not found there, sensible defaults will be used. .RS .RE @@ -499,34 +612,68 @@ For example: .PP By default, pandoc will include the following metadata elements: \f[C]<dc:title>\f[] (from the document title), \f[C]<dc:creator>\f[] -(from the document authors), \f[C]<dc:language>\f[] (from the locale), -and \f[C]<dc:identifier\ id="BookId">\f[] (a randomly generated UUID). +(from the document authors), \f[C]<dc:date>\f[] (from the document date, +which should be in ISO 8601 format), \f[C]<dc:language>\f[] (from the +\f[C]lang\f[] variable, or, if is not set, the locale), and +\f[C]<dc:identifier\ id="BookId">\f[] (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. .RE .TP -.B \f[C]-D\f[] \f[I]FORMAT\f[], -\f[C]--print-default-template=\f[]\f[I]FORMAT\f[] -Print the default template for an output \f[I]FORMAT\f[]. -(See \f[C]-t\f[] for a list of possible \f[I]FORMAT\f[]s.) +.B \f[C]--epub-embed-font=\f[]\f[I]FILE\f[] +Embed the specified font in the EPUB. +This option can be repeated to embed multiple fonts. +To use embedded fonts, you will need to add declarations like the +following to your CSS (see `\f[C]--epub-stylesheet\f[]): .RS +.IP +.nf +\f[C] +\@font-face\ { +font-family:\ DejaVuSans; +font-style:\ normal; +font-weight:\ normal; +src:url("DejaVuSans-Regular.ttf"); +} +\@font-face\ { +font-family:\ DejaVuSans; +font-style:\ normal; +font-weight:\ bold; +src:url("DejaVuSans-Bold.ttf"); +} +\@font-face\ { +font-family:\ DejaVuSans; +font-style:\ italic; +font-weight:\ normal; +src:url("DejaVuSans-Oblique.ttf"); +} +\@font-face\ { +font-family:\ DejaVuSans; +font-style:\ italic; +font-weight:\ bold; +src:url("DejaVuSans-BoldOblique.ttf"); +} +body\ {\ font-family:\ "DejaVuSans";\ } +\f[] +.fi .RE .TP -.B \f[C]-T\f[] \f[I]STRING\f[], \f[C]--title-prefix=\f[]\f[I]STRING\f[] -Specify \f[I]STRING\f[] as a prefix at the beginning of the title that -appears in the HTML header (but not in the title as it appears at the -beginning of the HTML body). -Implies \f[C]--standalone\f[]. +.B \f[C]--latex-engine=\f[]\f[I]pdflatex|lualatex|xelatex\f[] +Use the specified LaTeX engine when producing PDF output. +The default is \f[C]pdflatex\f[]. +If the engine is not in your PATH, the full path of the engine may be +specified here. .RS .RE +.SS Citations .TP .B \f[C]--bibliography=\f[]\f[I]FILE\f[] Specify bibliography database to be used in resolving citations. The database type will be determined from the extension of \f[I]FILE\f[], which may be \f[C].mods\f[] (MODS format), \f[C].bib\f[] -(BibTeX format), \f[C].bbx\f[] (BibLaTeX format), \f[C].ris\f[] (RIS -format), \f[C].enl\f[] (EndNote format), \f[C].xml\f[] (EndNote XML -format), \f[C].wos\f[] (ISI format), \f[C].medline\f[] (MEDLINE format), -\f[C].copac\f[] (Copac format), or \f[C].json\f[] (citeproc JSON). +(BibTeX/BibLaTeX format), \f[C].ris\f[] (RIS format), \f[C].enl\f[] +(EndNote format), \f[C].xml\f[] (EndNote XML format), \f[C].wos\f[] (ISI +format), \f[C].medline\f[] (MEDLINE format), \f[C].copac\f[] (Copac +format), or \f[C].json\f[] (citeproc JSON). If you want to use multiple bibliographies, just use this option repeatedly. .RS @@ -559,6 +706,29 @@ style: either \f[C]default.csl\f[] in the user data directory (see author-date style. .RE .TP +.B \f[C]--citation-abbreviations=\f[]\f[I]FILE\f[] +Specify a file containing abbreviations for journal titles and other +bibliographic fields (indicated by setting \f[C]form="short"\f[] in the +CSL node for the field). +The format is described at +\f[C]http://citationstylist.org/2011/10/19/abbreviations-for-zotero-test-release/\f[]. +Here is a short example: +.RS +.IP +.nf +\f[C] +{\ "default":\ { +\ \ \ \ "container-title":\ { +\ \ \ \ \ \ \ \ \ \ \ \ "Lloyd\[aq]s\ Law\ Reports":\ "Lloyd\[aq]s\ Rep", +\ \ \ \ \ \ \ \ \ \ \ \ "Estates\ Gazette":\ "EG", +\ \ \ \ \ \ \ \ \ \ \ \ "Scots\ Law\ Times":\ "SLT" +\ \ \ \ } +\ \ } +} +\f[] +.fi +.RE +.TP .B \f[C]--natbib\f[] Use natbib for citations in LaTeX output. .RS @@ -568,33 +738,71 @@ Use natbib for citations in LaTeX output. Use biblatex for citations in LaTeX output. .RS .RE +.SS Math rendering in HTML .TP -.B \f[C]--data-dir=\f[]\f[I]DIRECTORY\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: +.B \f[C]-m\f[] [\f[I]URL\f[]], \f[C]--latexmathml\f[][=\f[I]URL\f[]] +Use the LaTeXMathML script to display embedded TeX math in HTML output. +To insert a link to a local copy of the \f[C]LaTeXMathML.js\f[] script, +provide a \f[I]URL\f[]. +If no \f[I]URL\f[] is provided, the contents of the script will be +inserted directly into the HTML header, preserving portability at the +price of efficiency. +If you plan to use math on several pages, it is much better to link to a +copy of the script, so it can be cached. +.RS +.RE +.TP +.B \f[C]--mathml\f[][=\f[I]URL\f[]] +Convert TeX math to MathML (in \f[C]docbook\f[] as well as \f[C]html\f[] +and \f[C]html5\f[]). +In standalone \f[C]html\f[] output, a small javascript (or a link to +such a script if a \f[I]URL\f[] is supplied) will be inserted that +allows the MathML to be viewed on some browsers. +.RS +.RE +.TP +.B \f[C]--jsmath\f[][=\f[I]URL\f[]] +Use jsMath to display embedded TeX math in HTML output. +The \f[I]URL\f[] should point to the jsMath load script (e.g. +\f[C]jsMath/easy/load.js\f[]); if provided, it will be linked to in the +header of standalone HTML documents. +If a \f[I]URL\f[] is not provided, no link to the jsMath load script +will be inserted; it is then up to the author to provide such a link in +the HTML template. +.RS +.RE +.TP +.B \f[C]--mathjax\f[][=\f[I]URL\f[]] +Use MathJax to display embedded TeX math in HTML output. +The \f[I]URL\f[] should point to the \f[C]MathJax.js\f[] load script. +If a \f[I]URL\f[] is not provided, a link to the MathJax CDN will be +inserted. +.RS +.RE +.TP +.B \f[C]--gladtex\f[] +Enclose TeX math in \f[C]<eq>\f[] tags in HTML output. +These can then be processed by gladTeX to produce links to images of the +typeset formulas. +.RS +.RE +.TP +.B \f[C]--mimetex\f[][=\f[I]URL\f[]] +Render TeX math using the mimeTeX CGI script. +If \f[I]URL\f[] is not specified, it is assumed that the script is at +\f[C]/cgi-bin/mimetex.cgi\f[]. .RS -.IP -.nf -\f[C] -$HOME/.pandoc -\f[] -.fi -.PP -in unix and -.IP -.nf -\f[C] -C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc -\f[] -.fi -.PP -in Windows. -A \f[C]reference.odt\f[], \f[C]epub.css\f[], \f[C]templates\f[] -directory, or \f[C]s5\f[] directory placed in this directory will -override pandoc\[aq]s normal defaults. .RE .TP +.B \f[C]--webtex\f[][=\f[I]URL\f[]] +Render TeX formulas using an external script that converts TeX formulas +to images. +The formula will be concatenated with the URL provided. +If \f[I]URL\f[] is not specified, the Google Chart API will be used. +.RS +.RE +.SS Options for wrapper scripts +.TP .B \f[C]--dump-args\f[] Print information about command-line arguments to \f[I]stdout\f[], then exit. @@ -630,16 +838,6 @@ pandoc\ -o\ foo.html\ -s \f[] .fi .RE -.TP -.B \f[C]-v\f[], \f[C]--version\f[] -Print version. -.RS -.RE -.TP -.B \f[C]-h\f[], \f[C]--help\f[] -Show usage message. -.RS -.RE .SH TEMPLATES .PP When the \f[C]-s/--standalone\f[] option is used, pandoc uses a template @@ -725,7 +923,7 @@ date of document, as specified in title block .RE .TP .B \f[C]lang\f[] -language code for HTML documents +language code for HTML or LaTeX documents .RS .RE .TP @@ -739,6 +937,26 @@ base URL for Slidy documents (defaults to base URL for S5 documents (defaults to \f[C]ui/default\f[]) .RS .RE +.TP +.B \f[C]font-size\f[] +font size (10pt, 11pt, 12pt) for LaTeX documents +.RS +.RE +.TP +.B \f[C]documentclass\f[] +document class for LaTeX documents +.RS +.RE +.TP +.B \f[C]theme\f[] +theme for LaTeX beamer documents +.RS +.RE +.TP +.B \f[C]colortheme\f[] +colortheme for LaTeX beamer documents +.RS +.RE .PP Variables may be set at the command line using the \f[C]-V/--variable\f[] option. @@ -790,34 +1008,49 @@ modifying your custom templates accordingly. An easy way to do this is to fork the pandoc-templates repository (\f[C]http://github.com/jgm/pandoc-templates\f[]) and merge in changes after each pandoc release. -.SH PRODUCING HTML SLIDE SHOWS WITH PANDOC +.SH PRODUCING SLIDE SHOWS WITH PANDOC .PP You can use Pandoc to produce an HTML + javascript slide presentation that can be viewed via a web browser. -There are two ways to do this, using S5 or Slidy. +There are three ways to do this, using S5, DZSlides, or Slidy. +You can also produce a PDF slide show using LaTeX beamer. .PP Here\[aq]s the markdown source for a simple slide show, -\f[C]eating.txt\f[]: +\f[C]habits.txt\f[]: .IP .nf \f[C] -%\ Eating\ Habits +%\ Habits %\ John\ Doe %\ March\ 22,\ 2005 #\ In\ the\ morning +##\ Getting\ up + +-\ Turn\ off\ alarm +-\ Get\ out\ of\ bed + +##\ Breakfast + -\ Eat\ eggs -\ Drink\ coffee #\ In\ the\ evening +##\ Dinner + -\ Eat\ spaghetti -\ Drink\ wine --------------------------- +------------------  + +##\ Going\ to\ sleep + +-\ Get\ in\ bed +-\ Count\ sheep \f[] .fi .PP @@ -825,42 +1058,83 @@ To produce the slide show, simply type .IP .nf \f[C] -pandoc\ -w\ s5\ -s\ eating.txt\ >\ eating.html +pandoc\ -t\ s5\ -s\ habits.txt\ -o\ habits.html +\f[] +.fi +.PP +for S5, +.IP +.nf +\f[C] +pandoc\ -t\ slidy\ -s\ habits.txt\ -o\ habits.html \f[] .fi .PP -for S5, or +for Slidy, .IP .nf \f[C] -pandoc\ -w\ slidy\ -s\ eating.txt\ >\ eating.html +pandoc\ -t\ dzslides\ -s\ habits.txt\ -o\ habits.html \f[] .fi .PP -for Slidy. +for DZSlides, or +.IP +.nf +\f[C] +pandoc\ -t\ beamer\ habits.txt\ -o\ habits.pdf +\f[] +.fi +.PP +for beamer. +.PP +With all HTML slide formats, the \f[C]--self-contained\f[] option can be +used to produce a single file that contains all of the data necessary to +display the slide show, including linked scripts, stylesheets, images, +and videos. +.SS Structuring the slide show +.PP +By default, the \f[I]slide level\f[] is the highest header level in the +hierarchy that is followed immediately by content, and not another +header, somewhere in the document. +In the example above, level 1 headers are always followed by level 2 +headers, which are followed by content, so 2 is the slide level. +This default can be overridden using the \f[C]--slide-level\f[] option. .PP +The document is carved up into slides according to the following rules: +.IP \[bu] 2 +A horizontal rule always starts a new slide. +.IP \[bu] 2 +A header at the slide level always starts a new slide. +.IP \[bu] 2 +Headers \f[I]below\f[] the slide level in the hierarchy create headers +\f[I]within\f[] a slide. +.IP \[bu] 2 +Headers \f[I]above\f[] the slide level in the hierarchy create "title +slides," which just contain the section title and help to break the +slide show into sections. +.IP \[bu] 2 A title page is constructed automatically from the document\[aq]s title -block. -Each level-one header and horizontal rule begins a new slide. +block, if present. +(In the case of beamer, this can be disabled by commenting out some +lines in the default template.) +.PP +These rules are designed to support many different styles of slide show. +If you don\[aq]t care about structuring your slides into sections and +subsections, you can just use level 1 headers for all each slide. +(In that case, level 1 will be the slide level.) + But you can also structure the slide show into sections, as in the +example above. .PP -The file produced by pandoc with the \f[C]-s/--standalone\f[] option -embeds a link to javascripts and CSS files, which are assumed to be -available at the relative path \f[C]ui/default\f[] (for S5) or at the -Slidy website at \f[C]w3.org\f[] (for Slidy). +For Slidy and S5, the file produced by pandoc with the +\f[C]-s/--standalone\f[] option embeds a link to javascripts and CSS +files, which are assumed to be available at the relative path +\f[C]s5/default\f[] (for S5) or at the Slidy website at \f[C]w3.org\f[] +(for Slidy). (These paths can be changed by setting the \f[C]slidy-url\f[] or \f[C]s5-url\f[] variables; see \f[C]--variable\f[], above.) - If the \f[C]--offline\f[] option is specified, the scripts and CSS will -be included directly in the generated file, so that it may be used -offline. -.PP -You can change the style of the slides by putting customized CSS files -in \f[C]$DATADIR/s5/default\f[] (for S5) or \f[C]$DATADIR/slidy\f[] (for -Slidy), where \f[C]$DATADIR\f[] is the user data directory (see -\f[C]--data-dir\f[], above). -The originals may be found in pandoc\[aq]s system data directory -(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[]). -Pandoc will look there for any files it does not find in the user data -directory. + For DZSlides, the (relatively short) javascript and css are included in +the file by default. .SS Incremental lists .PP By default, these writers produces lists that display "all at once." If @@ -879,12 +1153,34 @@ with the \f[C]-i\f[] option), put it in a block quote: .PP In this way incremental and nonincremental lists can be mixed in a single document. +.SS Styling the slides +.PP +You can change the style of HTML slides by putting customized CSS files +in \f[C]$DATADIR/s5/default\f[] (for S5) or \f[C]$DATADIR/slidy\f[] (for +Slidy), where \f[C]$DATADIR\f[] is the user data directory (see +\f[C]--data-dir\f[], above). +The originals may be found in pandoc\[aq]s system data directory +(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[]). +Pandoc will look there for any files it does not find in the user data +directory. +.PP +For dzslides, the CSS is included in the HTML file itself, and may be +modified there. +.PP +To style beamer slides, you can specify a beamer "theme" or "colortheme" +using the \f[C]-V\f[] option: +.IP +.nf +\f[C] +pandoc\ -t\ beamer\ habits.txt\ -V\ theme:Warsaw\ -o\ habits.pdf +\f[] +.fi .SH LITERATE HASKELL SUPPORT .PP If you append \f[C]+lhs\f[] to an appropriate input or output format (\f[C]markdown\f[], \f[C]rst\f[], or \f[C]latex\f[] for input or output; -\f[C]html\f[] for output only), pandoc will treat the document as -literate Haskell source. +\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 @@ -892,9 +1188,10 @@ rather than block quotations. Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also be treated as Haskell code. .IP \[bu] 2 -In markdown output, code blocks with class \f[C]haskell\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 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). (This is because ghc treats \[aq]#\[aq] characters in column 1 as @@ -944,7 +1241,9 @@ This software carries no warranty of any kind. Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public, Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton, Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner, qerub, -Christopher Sawicki, Kelsey Hightower. +Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine +Latter, Ralf Stephan, Eric Seidel, B. +Scott Michel. .SH PANDOC'S MARKDOWN For a complete description of pandoc's extensions to standard markdown, see \f[C]pandoc_markdown\f[] (5). diff --git a/man/man5/pandoc_markdown.5 b/man/man5/pandoc_markdown.5 index 418b532e3..ad6c41e5d 100644 --- a/man/man5/pandoc_markdown.5 +++ b/man/man5/pandoc_markdown.5 @@ -1,5 +1,5 @@ .\"t -.TH PANDOC_MARKDOWN 5 "July 30, 2011" "Pandoc" +.TH PANDOC_MARKDOWN 5 "January 27, 2012" "Pandoc" .SH NAME pandoc_markdown - markdown syntax for pandoc(1) .SH DESCRIPTION @@ -39,7 +39,7 @@ line. Newlines are treated as spaces, so you can reflow your paragraphs as you like. If you need a hard line break, put two or more spaces at the end of a -line, or or type a backslash followed by a newline. +line, or type a backslash followed by a newline. .SH HEADERS .PP There are two kinds of headers, Setext and atx. @@ -98,12 +98,12 @@ I\ like\ several\ of\ their\ flavors\ of\ ice\ cream: #22,\ for\ example,\ and\ #5. \f[] .fi -.SS Header identifiers in HTML +.SS Header identifiers in HTML, LaTeX, and ConTeXt .PP \f[I]Pandoc extension\f[]. .PP -Each header element in pandoc\[aq]s HTML output is given a unique -identifier. +Each header element in pandoc\[aq]s HTML and ConTeXt output is given a +unique identifier. This identifier is based on the text of the header. To derive the identifier from the header text, .IP \[bu] 2 @@ -175,12 +175,12 @@ A link to this section, for example, might look like this: .nf \f[C] See\ the\ section\ on -[header\ identifiers](#header-identifiers-in-html). +[header\ identifiers][#header-identifiers-in-html]. \f[] .fi .PP Note, however, that this method of providing links to sections works -only in HTML. +only in HTML, LaTeX, and ConTeXt formats. .PP If the \f[C]--section-divs\f[] option is specified, then each section will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if @@ -275,9 +275,10 @@ Note: blank lines in the verbatim text need not begin with four spaces. .PP In addition to standard indented code blocks, Pandoc supports \f[I]delimited\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. -Everything between the tilde-lines is treated as code. +These begin with a row of three or more tildes (\f[C]~\f[]) or backticks +(\f[C]`\f[]) and end with a row of tildes or backticks that must be at +least as long as the starting row. +Everything between these lines is treated as code. No indentation is necessary: .IP .nf @@ -293,8 +294,8 @@ if\ (a\ >\ 3)\ { Like regular code blocks, delimited code blocks must be separated from surrounding text by blank lines. .PP -If the code itself contains a row of tildes, just use a longer row of -tildes at the start and end: +If the code itself contains a row of tildes or backticks, just use a +longer row of tildes or backticks at the start and end: .IP .nf \f[C] @@ -306,38 +307,63 @@ code\ including\ tildes \f[] .fi .PP -Optionally, you may specify the language of the code block using this +Optionally, you may attach attributes to the code block using this syntax: .IP .nf \f[C] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ {.haskell\ .numberLines} +~~~~\ {#mycode\ .haskell\ .numberLines\ startFrom="100"} qsort\ []\ \ \ \ \ =\ [] qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++ -\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)\ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \f[] .fi .PP +Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and +\f[C]numberLines\f[] are classes, and \f[C]startFrom\f[] is an attribute +with value \f[C]100\f[]. Some output formats can use this information to do syntax highlighting. -Currently, the only output format that uses this information is HTML. -.PP -If pandoc has been compiled with syntax highlighting support, then the -code block above will appear highlighted, with numbered lines. +Currently, the only output formats that uses this information are HTML +and LaTeX. +If highlighting is supported for your output format and language, then +the code block above will appear highlighted, with numbered lines. (To see which languages are supported, do \f[C]pandoc\ --version\f[].) -.PP -If pandoc has not been compiled with syntax highlighting support, the -code block above will appear as follows: + Otherwise, the code block above will appear as follows: .IP .nf \f[C] -<pre\ class="haskell"> +<pre\ id="mycode"\ class="haskell\ numberLines"\ startFrom="100"> \ \ <code> \ \ ... \ \ </code> </pre> \f[] .fi +.PP +A shortcut form can also be used for specifying the language of the code +block: +.IP +.nf +\f[C] +```haskell +qsort\ []\ =\ [] +``` +\f[] +.fi +.PP +This is equivalent to: +.IP +.nf +\f[C] +```\ {.haskell} +qsort\ []\ =\ [] +``` +\f[] +.fi +.PP +To prevent all highlighting, use the \f[C]--no-highlight\f[] flag. +To set the highlighting style, use \f[C]--highlight-style\f[]. .SH LISTS .SS Bullet lists .PP @@ -567,6 +593,8 @@ Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces. +The body of the definition (including the first line, aside from the +colon or tilde) should be indented four spaces. A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.) , each indented four spaces or one tab stop. @@ -698,9 +726,9 @@ one big list: <!--\ --> -a.\ \ uno -b.\ \ dos -c.\ \ tres +1.\ \ uno +2.\ \ dos +3.\ \ tres \f[] .fi .SH HORIZONTAL RULES @@ -1178,6 +1206,11 @@ described here. .RS .RE .TP +.B AsciiDoc +It will be rendered as \f[C]latexmath:[...]\f[]. +.RS +.RE +.TP .B Texinfo It will be rendered inside a \f[C]\@math\f[] command. .RS @@ -1198,19 +1231,31 @@ It will be rendered inside \f[C]<span\ class="math">\f[] tags. .RS .RE .TP -.B RTF, Docbook, OpenDocument, ODT +.B RTF, OpenDocument, ODT It will be rendered, if possible, using unicode characters, and will otherwise appear verbatim. .RS .RE .TP -.B HTML, Slidy, S5, EPUB +.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. +Otherwise it will be rendered, if possible, using unicode characters. +.RS +.RE +.TP +.B Docx +It will be rendered using OMML math markup. +.RS +.RE +.TP +.B HTML, Slidy, DZSlides, S5, EPUB The way math is rendered in HTML will depend on the command-line options selected: .RS .IP "1." 3 The default is to render TeX math as far as possible using unicode -characters, as with RTF, Docbook, and OpenDocument output. +characters, as with RTF, DocBook, and OpenDocument output. Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so that they may be styled differently from the surrounding text if needed. .IP "2." 3 @@ -1260,12 +1305,12 @@ If no URL is specified, the Google Chart API will be used .RE .SH RAW HTML .PP -Markdown allows you to insert raw HTML anywhere in a document (except -verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and \f[C]&\f[] are -interpreted literally). +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). .PP -The raw HTML is passed through unchanged in HTML, S5, Slidy, EPUB, -Markdown, and Textile output, and suppressed in other formats. +The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides, +EPUB, Markdown, and Textile output, and suppressed in other formats. .PP \f[I]Pandoc extension\f[]. .PP @@ -1575,16 +1620,11 @@ T}@T{ \&.mods T} T{ -BibTeX +BibTeX/BibLaTeX T}@T{ \&.bib T} T{ -BibLaTeX -T}@T{ -\&.bbx -T} -T{ RIS T}@T{ \&.ris |