From eac1fc3750923698db82011b9fda5a0788dfcfea Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sun, 23 Oct 2011 18:22:32 -0700 Subject: Added built man pages to repository. In general I don't like adding generated content to the repository, but I also want to make it possible to clone the repository and 'cabal install'. THe current system with Setup.hs calling MakeManPage.hs is too fragile. --- .gitignore | 2 - man/man1/markdown2pdf.1 | 170 +++++ man/man1/pandoc.1 | 971 +++++++++++++++++++++++++ man/man5/pandoc_markdown.5 | 1726 ++++++++++++++++++++++++++++++++++++++++++++ pandoc.cabal | 2 +- 5 files changed, 2868 insertions(+), 3 deletions(-) create mode 100644 man/man1/markdown2pdf.1 create mode 100644 man/man1/pandoc.1 create mode 100644 man/man5/pandoc_markdown.5 diff --git a/.gitignore b/.gitignore index df51012fa..710a6aa3a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,8 +3,6 @@ README.* !README.Debian INSTALL.* .configure-stamp -man/man?/*.1 -man/man?/*.5 man/man?/*.html *.diff pandoc.cabal.orig diff --git a/man/man1/markdown2pdf.1 b/man/man1/markdown2pdf.1 new file mode 100644 index 000000000..20c566c8d --- /dev/null +++ b/man/man1/markdown2pdf.1 @@ -0,0 +1,170 @@ +.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/pandoc.1 b/man/man1/pandoc.1 new file mode 100644 index 000000000..04e8b3469 --- /dev/null +++ b/man/man1/pandoc.1 @@ -0,0 +1,971 @@ +.TH PANDOC 1 "July 30, 2011" "Pandoc" +.SH NAME +pandoc - general markup converter +.SH SYNOPSIS +.PP +pandoc [\f[I]options\f[]] [\f[I]input-file\f[]]... +.SH DESCRIPTION +.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 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, DZSlides, or S5 HTML slide shows. +.PP +Pandoc\[aq]s enhanced version of markdown includes syntax for footnotes, +tables, flexible ordered lists, definition lists, delimited 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 +disabled using the \f[C]--strict\f[] option.) +.PP +In contrast to most existing tools for converting markdown to HTML, +which use regex substitutions, Pandoc has a modular design: it consists +of a set of readers, which parse text in a given format and produce a +native representation of the document, and a set of writers, which +convert this native representation into a target format. +Thus, adding an input or output format requires only adding a reader or +writer. +.SS Using Pandoc +.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). +For output to a file, use the \f[C]-o\f[] option: +.IP +.nf +\f[C] +pandoc\ -o\ output.html\ input.txt +\f[] +.fi +.PP +Instead of a file, an absolute URI may be given. +In this case pandoc will fetch the content using HTTP: +.IP +.nf +\f[C] +pandoc\ -f\ html\ -t\ markdown\ http://www.fsf.org +\f[] +.fi +.PP +If multiple input files are given, \f[C]pandoc\f[] will concatenate them +all (with blank lines between them) before parsing. +.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 +type: +.IP +.nf +\f[C] +pandoc\ -f\ markdown\ -t\ latex\ hello.txt +\f[] +.fi +.PP +To convert \f[C]hello.html\f[] from html to markdown: +.IP +.nf +\f[C] +pandoc\ -f\ html\ -t\ markdown\ hello.html +\f[] +.fi +.PP +Supported output formats are listed below under the \f[C]-t/--to\f[] +option. +Supported input formats are listed below under the \f[C]-f/--from\f[] +option. +Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and +\f[C]html\f[] readers are not complete; there are some constructs that +they do not parse. +.PP +If the input or output format is not specified explicitly, +\f[C]pandoc\f[] will attempt to guess it from the extensions of the +input and output filenames. +Thus, for example, +.IP +.nf +\f[C] +pandoc\ -o\ hello.tex\ hello.txt +\f[] +.fi +.PP +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. +.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 and +output through \f[C]iconv\f[]: +.IP +.nf +\f[C] +iconv\ -t\ utf-8\ input.txt\ |\ pandoc\ |\ iconv\ -f\ utf-8 +\f[] +.fi +.SH 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[] +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[] (markdown), +\f[C]textile\f[] (Textile), \f[C]rst\f[] (reStructuredText), +\f[C]html\f[] (HTML), or \f[C]latex\f[] (LaTeX). +If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[], or +\f[C]latex\f[], the input will be treated as literate Haskell source: +see Literate Haskell support, below. +.RS +.RE +.TP +.B \f[C]-t\f[] \f[I]FORMAT\f[], \f[C]-w\f[] \f[I]FORMAT\f[], +\f[C]--to=\f[]\f[I]FORMAT\f[], \f[C]--write=\f[]\f[I]FORMAT\f[] +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[] +(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]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). +.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.) +.RS +.RE +.TP +.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]--tab-stop=\f[]\f[I]NUMBER\f[] +Specify the number of spaces per tab (default is 4). +.RS +.RE +.TP +.B \f[C]--strict\f[] +Use strict markdown syntax, with no pandoc extensions or variants. +When the input format is HTML, this means that constructs that have no +equivalents in standard markdown (e.g. +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, +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 +\f[I]commands\f[], even if \f[C]-R\f[] is not specified.) +.RS +.RE +.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. +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[]. +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[].) +.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. +.RS +.RE +.TP +.B \f[C]--gladtex\f[] +Enclose TeX math in \f[C]\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 +.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 +.TP +.B \f[C]-i\f[], \f[C]--incremental\f[] +Make list items in Slidy, DZSlides or S5 display incrementally (one by +one). +The default is for lists to be displayed all at once. +.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. +.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. +.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]--section-divs\f[] +Wrap sections in \f[C]
\f[] tags (or \f[C]
\f[] tags in +HTML5), and attach identifiers to the enclosing \f[C]
\f[] (or +\f[C]
\f[]) rather than the header itself. +See Section identifiers, below. +.RS +.RE +.TP +.B \f[C]--no-wrap\f[] +Disable text wrapping in output. +By default, text is wrapped appropriately for the output format. +.RS +.RE +.TP +.B \f[C]--columns\f[]=\f[I]NUMBER\f[] +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 +create one) in the output document. +This option has no effect on \f[C]man\f[], \f[C]docbook\f[], +\f[C]slidy\f[], or \f[C]s5\f[] output. +.RS +.RE +.TP +.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]--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. +.RS +.RE +.TP +.B \f[C]-H\f[] \f[I]FILE\f[], \f[C]--include-in-header=\f[]\f[I]FILE\f[] +Include contents of \f[I]FILE\f[], verbatim, at the end of the header. +This can be used, for example, to include special CSS or javascript in +HTML documents. +This option can be used repeatedly to include multiple files in the +header. +They will be included in the order specified. +Implies \f[C]--standalone\f[]. +.RS +.RE +.TP +.B \f[C]-B\f[] \f[I]FILE\f[], +\f[C]--include-before-body=\f[]\f[I]FILE\f[] +Include contents of \f[I]FILE\f[], verbatim, at the beginning of the +document body (e.g. +after the \f[C]\f[] tag in HTML, or the \f[C]\\begin{document}\f[] +command in LaTeX). +This can be used to include navigation bars or banners in HTML +documents. +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[C]--standalone\f[]. +.RS +.RE +.TP +.B \f[C]-A\f[] \f[I]FILE\f[], +\f[C]--include-after-body=\f[]\f[I]FILE\f[] +Include contents of \f[I]FILE\f[], verbatim, at the end of the document +body (before the \f[C]\f[] tag in HTML, or the +\f[C]\\end{document}\f[] command in LaTeX). +This option can be be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[C]--standalone\f[]. +.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. +For best results, the reference ODT should be a modified version of an +ODT produced using pandoc. +The contents of the reference ODT are ignored, but its stylesheets are +used in the new ODT. +If no reference ODT is specified on the command line, pandoc will look +for a file \f[C]reference.odt\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). +If it is not found there, sensible defaults will be used. +.RS +.RE +.TP +.B \f[C]--epub-cover-image=\f[]\f[I]FILE\f[] +Use the specified image as the EPUB cover. +It is recommended that the image be less than 1000px in width and +height. +.RS +.RE +.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 \f[C]http://dublincore.org/documents/dces/\f[]. +For example: +.RS +.IP +.nf +\f[C] +\ Creative\ Commons +\ es-AR +\f[] +.fi +.PP +By default, pandoc will include the following metadata elements: +\f[C]\f[] (from the document title), \f[C]\f[] +(from the document authors), \f[C]\f[] (from the locale), +and \f[C]\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.) +.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]--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/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 +.RE +.TP +.B \f[C]--csl=\f[]\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 \f[C]--natbib\f[] +Use natbib for citations in LaTeX output. +.RS +.RE +.TP +.B \f[C]--biblatex\f[] +Use biblatex for citations in LaTeX output. +.RS +.RE +.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: +.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]--dump-args\f[] +Print information about command-line arguments to \f[I]stdout\f[], then +exit. +This option is intended primarily for use in wrapper scripts. +The first line of output contains the name of the output file specified +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 +include any options appearing after a \f[C]--\f[] separator at the end +of the line. +.RS +.RE +.TP +.B \f[C]--ignore-args\f[] +Ignore command-line arguments (for use in wrapper scripts). +Regular Pandoc options are not ignored. +Thus, for example, +.RS +.IP +.nf +\f[C] +pandoc\ --ignore-args\ -o\ foo.html\ -s\ foo.txt\ --\ -e\ latin1 +\f[] +.fi +.PP +is equivalent to +.IP +.nf +\f[C] +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 +to add header and footer material that is needed for a self-standing +document. +To see the default template that is used, just type +.IP +.nf +\f[C] +pandoc\ -D\ FORMAT +\f[] +.fi +.PP +where \f[C]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 +\f[C]--data-dir\f[], above). +.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 +.IP +.nf +\f[C] +$title$ +\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: +.TP +.B \f[C]header-includes\f[] +contents specified by \f[C]-H/--include-in-header\f[] (may have multiple +values) +.RS +.RE +.TP +.B \f[C]toc\f[] +non-null value if \f[C]--toc/--table-of-contents\f[] was specified +.RS +.RE +.TP +.B \f[C]include-before\f[] +contents specified by \f[C]-B/--include-before-body\f[] (may have +multiple values) +.RS +.RE +.TP +.B \f[C]include-after\f[] +contents specified by \f[C]-A/--include-after-body\f[] (may have +multiple values) +.RS +.RE +.TP +.B \f[C]body\f[] +body of document +.RS +.RE +.TP +.B \f[C]title\f[] +title of document, as specified in title block +.RS +.RE +.TP +.B \f[C]author\f[] +author of document, as specified in title block (may have multiple +values) +.RS +.RE +.TP +.B \f[C]date\f[] +date of document, as specified in title block +.RS +.RE +.TP +.B \f[C]lang\f[] +language code for HTML documents +.RS +.RE +.TP +.B \f[C]slidy-url\f[] +base URL for Slidy documents (defaults to +\f[C]http://www.w3.org/Talks/Tools/Slidy2\f[]) +.RS +.RE +.TP +.B \f[C]s5-url\f[] +base URL for S5 documents (defaults to \f[C]ui/default\f[]) +.RS +.RE +.PP +Variables may be set at the command line using the +\f[C]-V/--variable\f[] option. +This allows users to include custom variables in their templates. +.PP +Templates may contain conditionals. +The syntax is as follows: +.IP +.nf +\f[C] +$if(variable)$ +X +$else$ +Y +$endif$ +\f[] +.fi +.PP +This will include \f[C]X\f[] in the template if \f[C]variable\f[] has a +non-null value; otherwise it will include \f[C]Y\f[]. +\f[C]X\f[] and \f[C]Y\f[] are placeholders for any valid template text, +and may include interpolated variables or other conditionals. +The \f[C]$else$\f[] section may be omitted. +.PP +When variables can have multiple values (for example, \f[C]author\f[] in +a multi-author document), you can use the \f[C]$for$\f[] keyword: +.IP +.nf +\f[C] +$for(author)$ + +$endfor$ +\f[] +.fi +.PP +You can optionally specify a separator to be used between consecutive +items: +.IP +.nf +\f[C] +$for(author)$$author$$sep$,\ $endfor$ +\f[] +.fi +.PP +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 +(\f[C]http://github.com/jgm/pandoc-templates\f[]) and merge in changes +after each pandoc release. +.SH PRODUCING HTML 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 three ways to do this, using S5, DZSlides, or Slidy. +.PP +Here\[aq]s the markdown source for a simple slide show, +\f[C]eating.txt\f[]: +.IP +.nf +\f[C] +%\ Eating\ Habits +%\ John\ Doe +%\ March\ 22,\ 2005 + +#\ In\ the\ morning + +-\ Eat\ eggs +-\ Drink\ coffee + +#\ In\ the\ evening + +-\ Eat\ spaghetti +-\ Drink\ wine + +-------------------------- + +![picture\ of\ spaghetti](images/spaghetti.jpg) +\f[] +.fi +.PP +To produce the slide show, simply type +.IP +.nf +\f[C] +pandoc\ -w\ s5\ -s\ eating.txt\ >\ eating.html +\f[] +.fi +.PP +for S5, or +.IP +.nf +\f[C] +pandoc\ -w\ slidy\ -s\ eating.txt\ >\ eating.html +\f[] +.fi +.PP +for Slidy, or +.IP +.nf +\f[C] +pandoc\ -w\ dzslides\ -s\ eating.txt\ >\ eating.html +\f[] +.fi +.PP +for DZSlides. +.PP +A title page is constructed automatically from the document\[aq]s title +block. +Each level-one header and horizontal rule begins a new slide. +.PP +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]ui/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. +For DZSlides, the (relatively short) javascript and css are included in +the file by default. +.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. +.SS Incremental lists +.PP +By default, these writers produces lists that display "all at once." If +you want your lists to display incrementally (one item at a time), use +the \f[C]-i\f[] option. +If you want a particular list to depart from the default (that is, to +display incrementally without the \f[C]-i\f[] option and all at once +with the \f[C]-i\f[] option), put it in a block quote: +.IP +.nf +\f[C] +>\ -\ Eat\ spaghetti +>\ -\ Drink\ wine +\f[] +.fi +.PP +In this way incremental and nonincremental lists can be mixed in a +single document. +.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. +This means that +.IP \[bu] 2 +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. +.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 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 +introducing line numbers.) +.IP \[bu] 2 +In restructured text input, "bird track" sections will be parsed as +Haskell code. +.IP \[bu] 2 +In restructured text output, code blocks with class \f[C]haskell\f[] +will be rendered using bird tracks. +.IP \[bu] 2 +In LaTeX input, text in \f[C]code\f[] environments will be parsed as +Haskell code. +.IP \[bu] 2 +In LaTeX output, code blocks with class \f[C]haskell\f[] will be +rendered inside \f[C]code\f[] environments. +.IP \[bu] 2 +In HTML output, code blocks with class \f[C]haskell\f[] will be rendered +with class \f[C]literatehaskell\f[] and bird tracks. +.PP +Examples: +.IP +.nf +\f[C] +pandoc\ -f\ markdown+lhs\ -t\ html +\f[] +.fi +.PP +reads literate Haskell source formatted with markdown conventions and +writes ordinary HTML (without bird tracks). +.IP +.nf +\f[C] +pandoc\ -f\ markdown+lhs\ -t\ html+lhs +\f[] +.fi +.PP +writes HTML with the Haskell code in bird tracks, so it can be copied +and pasted as literate Haskell source. +.SH AUTHORS +.PP +© 2006-2011 John MacFarlane (jgm at berkeley dot edu). +Released under the GPL, version 2 or greater. +This software carries no warranty of any kind. +(See COPYRIGHT for full copyright and warranty notices.) + Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang, +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. +.SH PANDOC'S MARKDOWN +For a complete description of pandoc's extensions to standard markdown, +see \f[C]pandoc_markdown\f[] (5). +.SH SEE ALSO +.PP +\f[C]markdown2pdf\f[] (1), \f[C]pandoc_markdown\f[] (5). +.PP +The Pandoc source code and all documentation may be downloaded +from . diff --git a/man/man5/pandoc_markdown.5 b/man/man5/pandoc_markdown.5 new file mode 100644 index 000000000..f7a4e22f7 --- /dev/null +++ b/man/man5/pandoc_markdown.5 @@ -0,0 +1,1726 @@ +.\"t +.TH PANDOC_MARKDOWN 5 "July 30, 2011" "Pandoc" +.SH NAME +pandoc_markdown - markdown syntax for pandoc(1) +.SH DESCRIPTION +.PP +Pandoc understands an extended and slightly revised version of John +Gruber\[aq]s markdown syntax. +This document explains the syntax, noting differences from standard +markdown. +Except where noted, these differences can be suppressed by specifying +the \f[C]--strict\f[] command-line option. +.SH PHILOSOPHY +.PP +Markdown is designed to be easy to write, and, even more importantly, +easy to read: +.RS +.PP +A Markdown-formatted document should be publishable as-is, as plain +text, without looking like it\[aq]s been marked up with tags or +formatting instructions. +-- John Gruber +.RE +.PP +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, +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 +elements like definition lists, tables, mathematics, and footnotes. +.SH PARAGRAPHS +.PP +A paragraph is one or more lines of text followed by one or more blank +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 type a backslash followed by a newline. +.SH HEADERS +.PP +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 +\f[C]=\f[] signs (for a level one header) of \f[C]-\f[] signs (for a +level two header): +.IP +.nf +\f[C] +A\ level-one\ header +================== + +A\ level-two\ header +------------------ +\f[] +.fi +.PP +The header text can contain inline formatting, such as emphasis (see +Inline formatting, below). +.SS Atx-style headers +.PP +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: +.IP +.nf +\f[C] +##\ A\ level-two\ header + +###\ A\ level-three\ header\ ### +\f[] +.fi +.PP +As with setext-style headers, the header text can contain formatting: +.IP +.nf +\f[C] +#\ A\ level-one\ header\ with\ a\ [link](/url)\ and\ *emphasis* +\f[] +.fi +.PP +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 +\f[C]#\f[] to end up at the beginning of a line by accident (perhaps +through line wrapping). +Consider, for example: +.IP +.nf +\f[C] +I\ like\ several\ of\ their\ flavors\ of\ ice\ cream: +#22,\ for\ example,\ and\ #5. +\f[] +.fi +.SS Header identifiers in HTML +.PP +\f[I]Pandoc extension\f[]. +.PP +Each header element in pandoc\[aq]s HTML 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 +Remove all formatting, links, etc. +.IP \[bu] 2 +Remove all punctuation, except underscores, hyphens, and periods. +.IP \[bu] 2 +Replace all spaces and newlines with hyphens. +.IP \[bu] 2 +Convert all alphabetic characters to lowercase. +.IP \[bu] 2 +Remove everything up to the first letter (identifiers may not begin with +a number or punctuation mark). +.IP \[bu] 2 +If nothing is left after this, use the identifier \f[C]section\f[]. +.PP +Thus, for example, +.PP +.TS +tab(@); +l l. +T{ +Header +T}@T{ +Identifier +T} +_ +T{ +Header identifiers in HTML +T}@T{ +\f[C]header-identifiers-in-html\f[] +T} +T{ +\f[I]Dogs\f[]?--in \f[I]my\f[] house? +T}@T{ +\f[C]dogs--in-my-house\f[] +T} +T{ +HTML, S5, or RTF? +T}@T{ +\f[C]html-s5-or-rtf\f[] +T} +T{ +3. +Applications +T}@T{ +\f[C]applications\f[] +T} +T{ +33 +T}@T{ +\f[C]section\f[] +T} +.TE +.PP +These rules should, in most cases, allow one to determine the identifier +from the header text. +The exception is when several headers have the same text; in this case, +the first will get an identifier as described above; the second will get +the same identifier with \f[C]-1\f[] appended; the third with +\f[C]-2\f[]; and so on. +.PP +These identifiers are used to provide link targets in the table of +contents generated by the \f[C]--toc|--table-of-contents\f[] option. +They also make it easy to provide links from one section of a document +to another. +A link to this section, for example, might look like this: +.IP +.nf +\f[C] +See\ the\ section\ on +[header\ identifiers](#header-identifiers-in-html). +\f[] +.fi +.PP +Note, however, that this method of providing links to sections works +only in HTML. +.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 +\f[C]--html5\f[] was specified), and the identifier will be attached to +the enclosing \f[C]
\f[] (or \f[C]
\f[]) tag rather than the +header itself. +This allows entire sections to be manipulated using javascript or +treated differently in CSS. +.SH BLOCK QUOTATIONS +.PP +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. +(The \f[C]>\f[] need not start at the left margin, but it should not be +indented more than three spaces.) +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote.\ This +>\ paragraph\ has\ two\ lines. +> +>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote. +>\ 2.\ Second\ item. +\f[] +.fi +.PP +A "lazy" form, which requires the \f[C]>\f[] character only on the first +line of each block, is also allowed: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote.\ This +paragraph\ has\ two\ lines. + +>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote. +2.\ Second\ item. +\f[] +.fi +.PP +Among the block elements that can be contained in a block quote are +other block quotes. +That is, block quotes can be nested: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote. +> +>\ >\ A\ block\ quote\ within\ a\ block\ quote. +\f[] +.fi +.PP +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). +The reason for the requirement is that it is all too easy for a +\f[C]>\f[] to end up at the beginning of a line by accident (perhaps +through line wrapping). +So, unless \f[C]--strict\f[] is used, the following does not produce a +nested block quote in pandoc: +.IP +.nf +\f[C] +>\ This\ is\ a\ block\ quote. +>>\ Nested. +\f[] +.fi +.SH VERBATIM (CODE) BLOCKS +.SS Indented code blocks +.PP +A block of text indented four spaces (or one tab) is treated as verbatim +text: that is, special characters do not trigger special formatting, and +all spaces and line breaks are preserved. +For example, +.IP +.nf +\f[C] +\ \ \ \ if\ (a\ >\ 3)\ { +\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN); +\ \ \ \ } +\f[] +.fi +.PP +The initial (four space or one tab) indentation is not considered part +of the verbatim text, and is removed in the output. +.PP +Note: blank lines in the verbatim text need not begin with four spaces. +.SS Delimited code blocks +.PP +\f[I]Pandoc extension\f[]. +.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. +No indentation is necessary: +.IP +.nf +\f[C] +~~~~~~~ +if\ (a\ >\ 3)\ { +\ \ moveShip(5\ *\ gravity,\ DOWN); +} +~~~~~~~ +\f[] +.fi +.PP +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: +.IP +.nf +\f[C] +~~~~~~~~~~~~~~~~ +~~~~~~~~~~ +code\ including\ tildes +~~~~~~~~~~ +~~~~~~~~~~~~~~~~ +\f[] +.fi +.PP +Optionally, you may specify the language of the code block using this +syntax: +.IP +.nf +\f[C] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ {.haskell\ .numberLines} +qsort\ []\ \ \ \ \ =\ [] +qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++ +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)\ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +\f[] +.fi +.PP +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. +(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: +.IP +.nf +\f[C] + +\ \ +\ \ ... +\ \ + +\f[] +.fi +.SH LISTS +.SS Bullet lists +.PP +A bullet list is a list of bulleted list items. +A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or +\f[C]-\f[]). +Here is a simple example: +.IP +.nf +\f[C] +*\ one +*\ two +*\ three +\f[] +.fi +.PP +This will produce a "compact" list. +If you want a "loose" list, in which each item is formatted as a +paragraph, put spaces between the items: +.IP +.nf +\f[C] +*\ one + +*\ two + +*\ three +\f[] +.fi +.PP +The bullets need not be flush with the left margin; they may be indented +one, two, or three spaces. +The bullet must be followed by whitespace. +.PP +List items look best if subsequent lines are flush with the first line +(after the bullet): +.IP +.nf +\f[C] +*\ here\ is\ my\ first +\ \ list\ item. +*\ and\ my\ second. +\f[] +.fi +.PP +But markdown also allows a "lazy" format: +.IP +.nf +\f[C] +*\ here\ is\ my\ first +list\ item. +*\ and\ my\ second. +\f[] +.fi +.SS The four-space rule +.PP +A list item may contain multiple paragraphs and other block-level +content. +However, subsequent paragraphs must be preceded by a blank line and +indented four spaces or a tab. +The list will look better if the first paragraph is aligned with the +rest: +.IP +.nf +\f[C] +\ \ *\ First\ paragraph. + +\ \ \ \ Continued. + +\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented +\ \ \ \ eight\ spaces: + +\ \ \ \ \ \ \ \ {\ code\ } +\f[] +.fi +.PP +List items may include other lists. +In this case the preceding blank line is optional. +The nested list must be indented four spaces or one tab: +.IP +.nf +\f[C] +*\ fruits +\ \ \ \ +\ apples +\ \ \ \ \ \ \ \ -\ macintosh +\ \ \ \ \ \ \ \ -\ red\ delicious +\ \ \ \ +\ pears +\ \ \ \ +\ peaches +*\ vegetables +\ \ \ \ +\ brocolli +\ \ \ \ +\ chard +\f[] +.fi +.PP +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. +.IP +.nf +\f[C] ++\ A\ lazy,\ lazy,\ list +item. + ++\ Another\ one;\ this\ looks +bad\ but\ is\ legal. + +\ \ \ \ Second\ paragraph\ of\ second +list\ item. +\f[] +.fi +.PP +\f[B]Note:\f[] Although the four-space rule for continuation paragraphs +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 +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 +(including nested lists), and pandoc interprets it that way. +.SS Ordered lists +.PP +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 +period and a space. +The numbers themselves are ignored, so there is no difference between +this list: +.IP +.nf +\f[C] +1.\ \ one +2.\ \ two +3.\ \ three +\f[] +.fi +.PP +and this one: +.IP +.nf +\f[C] +5.\ \ one +7.\ \ two +1.\ \ three +\f[] +.fi +.PP +\f[I]Pandoc extension\f[]. +.PP +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 +right-parentheses or period. +They must be separated from the text that follows by at least one space, +and, if the list marker is a capital letter with a period, by at least +two spaces.[1] +.PP +Pandoc also pays attention to the type of list marker used, and to the +starting number, and both of these are preserved where possible in the +output format. +Thus, the following yields a list with numbers followed by a single +parenthesis, starting with 9, and a sublist with lowercase roman +numerals: +.IP +.nf +\f[C] +\ 9)\ \ Ninth +10)\ \ Tenth +11)\ \ Eleventh +\ \ \ \ \ \ \ i.\ subone +\ \ \ \ \ \ ii.\ subtwo +\ \ \ \ \ iii.\ subthree +\f[] +.fi +.PP +Note that Pandoc pays attention only to the \f[I]starting\f[] marker in +a list. +So, the following yields a list numbered sequentially starting from 2: +.IP +.nf +\f[C] +(2)\ Two +(5)\ Three +1.\ \ Four +*\ \ \ Five +\f[] +.fi +.PP +If default list markers are desired, use \f[C]#.\f[]: +.IP +.nf +\f[C] +#.\ \ one +#.\ \ two +#.\ \ three +\f[] +.fi +.SS Definition lists +.PP +\f[I]Pandoc extension\f[]. +.PP +Pandoc supports definition lists, using a syntax inspired by PHP +Markdown Extra and reStructuredText:[2] +.IP +.nf +\f[C] +Term\ 1 + +:\ \ \ Definition\ 1 + +Term\ 2\ with\ *inline\ markup* + +:\ \ \ Definition\ 2 + +\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ } + +\ \ \ \ Third\ paragraph\ of\ definition\ 2. +\f[] +.fi +.PP +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. +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. +.PP +If you leave space after the definition (as in the example above), the +blocks of the definitions will be considered paragraphs. +In some output formats, this will mean greater spacing between +term/definition pairs. +For a compact definition list, do not leave space between the definition +and the next term: +.IP +.nf +\f[C] +Term\ 1 +\ \ ~\ Definition\ 1 +Term\ 2 +\ \ ~\ Definition\ 2a +\ \ ~\ Definition\ 2b +\f[] +.fi +.SS Numbered example lists +.PP +\f[I]Pandoc extension\f[]. +.PP +The special list marker \f[C]\@\f[] can be used for sequentially +numbered examples. +The first list item with a \f[C]\@\f[] marker will be numbered +\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document. +The numbered examples need not occur in a single list; each new list +using \f[C]\@\f[] will take up where the last stopped. +So, for example: +.IP +.nf +\f[C] +(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1). +(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2). + +Explanation\ of\ examples. + +(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3). +\f[] +.fi +.PP +Numbered examples can be labeled and referred to elsewhere in the +document: +.IP +.nf +\f[C] +(\@good)\ \ This\ is\ a\ good\ example. + +As\ (\@good)\ illustrates,\ ... +\f[] +.fi +.PP +The label can be any string of alphanumeric characters, underscores, or +hyphens. +.SS Compact and loose lists +.PP +Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge +cases" involving lists. +Consider this source: +.IP +.nf +\f[C] ++\ \ \ First ++\ \ \ Second: +\ -\ \ \ Fee +\ -\ \ \ Fie +\ -\ \ \ Foe + ++\ \ \ Third +\f[] +.fi +.PP +Pandoc transforms this into a "compact list" (with no \f[C]

\f[] tags +around "First", "Second", or "Third"), while markdown puts \f[C]

\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, +it is treated as a paragraph. +Since "Second" is followed by a list, and not a blank line, it isn\[aq]t +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]--strict\f[] option is +specified. +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 +.PP +What if you want to put an indented code block after a list? +.IP +.nf +\f[C] +-\ \ \ item\ one +-\ \ \ item\ two + +\ \ \ \ {\ my\ code\ block\ } +\f[] +.fi +.PP +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 +To "cut off" the list after item two, you can insert some non-indented +content, like an HTML comment, which won\[aq]t produce visible output in +any format: +.IP +.nf +\f[C] +-\ \ \ item\ one +-\ \ \ item\ two + + + +\ \ \ \ {\ my\ code\ block\ } +\f[] +.fi +.PP +You can use the same trick if you want two consecutive lists instead of +one big list: +.IP +.nf +\f[C] +1.\ \ one +2.\ \ two +3.\ \ three + + + +a.\ \ uno +b.\ \ dos +c.\ \ tres +\f[] +.fi +.SH HORIZONTAL RULES +.PP +A line containing a row of three or more \f[C]*\f[], \f[C]-\f[], or +\f[C]_\f[] characters (optionally separated by spaces) produces a +horizontal rule: +.IP +.nf +\f[C] +*\ \ *\ \ *\ \ * + +--------------- +\f[] +.fi +.SH TABLES +.PP +\f[I]Pandoc extension\f[]. +.PP +Three kinds of tables may be used. +All three kinds presuppose the use of a fixed-width font, such as +Courier. +.PP +\f[B]Simple tables\f[] look like this: +.IP +.nf +\f[C] +\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default +-------\ \ \ \ \ ------\ ----------\ \ \ ------- +\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12 +\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123 +\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1 + +Table:\ \ Demonstration\ of\ simple\ table\ syntax. +\f[] +.fi +.PP +The headers and table rows must each fit on one line. +Column alignments are determined by the position of the header text +relative to the dashed line below it:[3] +.IP \[bu] 2 +If the dashed line is flush with the header text on the right side but +extends beyond it on the left, the column is right-aligned. +.IP \[bu] 2 +If the dashed line is flush with the header text on the left side but +extends beyond it on the right, the column is left-aligned. +.IP \[bu] 2 +If the dashed line extends beyond the header text on both sides, the +column is centered. +.IP \[bu] 2 +If the dashed line is flush with the header text on both sides, the +default alignment is used (in most cases, this will be left). +.PP +The table must end with a blank line, or a line of dashes followed by a +blank line. +A caption may optionally be provided (as illustrated in the example +above). +A caption is a paragraph beginning with the string \f[C]Table:\f[] (or +just \f[C]:\f[]), which will be stripped off. +It may appear either before or after the table. +.PP +The column headers may be omitted, provided a dashed line is used to end +the table. +For example: +.IP +.nf +\f[C] +-------\ \ \ \ \ ------\ ----------\ \ \ ------- +\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12 +\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123 +\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1 +-------\ \ \ \ \ ------\ ----------\ \ \ ------- +\f[] +.fi +.PP +When headers are omitted, column alignments are determined on the basis +of the first line of the table body. +So, in the tables above, the columns would be right, left, center, and +right aligned, respectively. +.PP +\f[B]Multiline tables\f[] allow headers and table rows to span multiple +lines of text (but cells that span multiple columns or rows of the table +are not supported). +Here is an example: +.IP +.nf +\f[C] +------------------------------------------------------------- +\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left +\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned +-----------\ -------\ ---------------\ ------------------------- +\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines. + +\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows. +------------------------------------------------------------- + +Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span +multiple\ lines. +\f[] +.fi +.PP +These work like simple tables, but with the following differences: +.IP \[bu] 2 +They must begin with a row of dashes, before the header text (unless the +headers are omitted). +.IP \[bu] 2 +They must end with a row of dashes, then a blank line. +.IP \[bu] 2 +The rows must be separated by blank lines. +.PP +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. +.PP +Headers may be omitted in multiline tables as well as simple tables: +.IP +.nf +\f[C] +-----------\ -------\ ---------------\ ------------------------- +\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines. + +\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows. +------------------------------------------------------------- + +:\ Here\[aq]s\ a\ multiline\ table\ without\ headers. +\f[] +.fi +.PP +It is possible for a multiline table to have just one row, but the row +should be followed by a blank line (and then the row of dashes that ends +the table), or the table may be interpreted as a simple table. +.PP +\f[B]Grid tables\f[] look like this: +.IP +.nf +\f[C] +:\ Sample\ grid\ table. + ++---------------+---------------+--------------------+ +|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ | ++===============+===============+====================+ +|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ -\ built-in\ wrapper\ | +|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ bright\ color\ \ \ \ \ | ++---------------+---------------+--------------------+ +|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ -\ cures\ scurvy\ \ \ \ \ | +|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ tasty\ \ \ \ \ \ \ \ \ \ \ \ | ++---------------+---------------+--------------------+ +\f[] +.fi +.PP +The row of \f[C]=\f[]s separates the header from the table body, and can +be omitted for a headerless table. +The cells of grid tables may contain arbitrary block elements (multiple +paragraphs, code blocks, lists, etc.) +\&. +Alignments are not supported, nor are cells that span multiple columns +or rows. +Grid tables can be created easily using Emacs table mode. +.SH TITLE BLOCK +.PP +\f[I]Pandoc extension\f[]. +.PP +If the file begins with a title block +.IP +.nf +\f[C] +%\ title +%\ author(s)\ (separated\ by\ semicolons) +%\ date +\f[] +.fi +.PP +it will be parsed as bibliographic information, not regular text. +(It will be used, for example, in the title of standalone LaTeX or HTML +output.) + The block may contain just a title, a title and an author, or all three +elements. +If you want to include an author but no title, or a title and a date but +no author, you need a blank line: +.IP +.nf +\f[C] +% +%\ Author + +%\ My\ title +% +%\ June\ 15,\ 2006 +\f[] +.fi +.PP +The title may occupy multiple lines, but continuation lines must begin +with leading space, thus: +.IP +.nf +\f[C] +%\ My\ title +\ \ on\ multiple\ lines +\f[] +.fi +.PP +If a document has multiple authors, the authors may be put on separate +lines with leading space, or separated by semicolons, or both. +So, all of the following are equivalent: +.IP +.nf +\f[C] +%\ Author\ One +\ \ Author\ Two + +%\ Author\ One;\ Author\ Two + +%\ Author\ One; +\ \ Author\ Two +\f[] +.fi +.PP +The date must fit on one line. +.PP +All three metadata fields may contain standard inline formatting +(italics, links, footnotes, etc.) +\&. +.PP +Title blocks will always be parsed, but they will affect the output only +when the \f[C]--standalone\f[] (\f[C]-s\f[]) option is chosen. +In HTML output, titles will appear twice: once in the document head -- +this is the title that will appear at the top of the window in a browser +-- and once at the beginning of the document body. +The title in the document head can have an optional prefix attached +(\f[C]--title-prefix\f[] or \f[C]-T\f[] option). +The title in the body appears as an H1 element with class "title", so it +can be suppressed or reformatted with CSS. +If a title prefix is specified with \f[C]-T\f[] and no title block +appears in the document, the title prefix will be used by itself as the +HTML title. +.PP +The man page writer extracts a title, man page section number, and other +header and footer information from the title line. +The title is assumed to be the first word on the title line, which may +optionally end with a (single-digit) section number in parentheses. +(There should be no space between the title and the parentheses.) + Anything after this is assumed to be additional footer and header text. +A single pipe character (\f[C]|\f[]) should be used to separate the +footer text from the header text. +Thus, +.IP +.nf +\f[C] +%\ PANDOC(1) +\f[] +.fi +.PP +will yield a man page with the title \f[C]PANDOC\f[] and section 1. +.IP +.nf +\f[C] +%\ PANDOC(1)\ Pandoc\ User\ Manuals +\f[] +.fi +.PP +will also have "Pandoc User Manuals" in the footer. +.IP +.nf +\f[C] +%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0 +\f[] +.fi +.PP +will also have "Version 4.0" in the header. +.SH BACKSLASH ESCAPES +.PP +Except inside a code block or inline code, any punctuation or space +character preceded by a backslash will be treated literally, even if it +would normally indicate formatting. +Thus, for example, if one writes +.IP +.nf +\f[C] +*\\*hello\\** +\f[] +.fi +.PP +one will get +.IP +.nf +\f[C] +*hello* +\f[] +.fi +.PP +instead of +.IP +.nf +\f[C] +hello +\f[] +.fi +.PP +This rule is easier to remember than standard markdown\[aq]s rule, which +allows only the following characters to be backslash-escaped: +.IP +.nf +\f[C] +\\`*_{}[]()>#+-.! +\f[] +.fi +.PP +(However, if the \f[C]--strict\f[] option is supplied, the standard +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 +\f[C]\\ \f[] or \f[C]\\ \f[]. +.PP +A backslash-escaped newline (i.e. +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]\f[]. +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. +.SH SMART PUNCTUATION +.PP +If the \f[C]--smart\f[] option is specified, pandoc will produce +typographically correct output, converting straight quotes to curly +quotes, \f[C]---\f[] and \f[C]--\f[] to Em-dashes, and \f[C]...\f[] to +ellipses. +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. +.SH INLINE FORMATTING +.SS Emphasis +.PP +To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or +\f[C]_\f[], like this: +.IP +.nf +\f[C] +This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this +is\ *emphasized\ with\ asterisks*. +\f[] +.fi +.PP +Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]: +.IP +.nf +\f[C] +This\ is\ **strong\ emphasis**\ and\ __with\ underscores__. +\f[] +.fi +.PP +A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or +backslash-escaped, will not trigger emphasis: +.IP +.nf +\f[C] +This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*. +\f[] +.fi +.PP +Because \f[C]_\f[] is sometimes used inside words and identifiers, +pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric +characters as an emphasis marker. +If you want to emphasize just part of a word, use \f[C]*\f[]: +.IP +.nf +\f[C] +feas*ible*,\ not\ feas*able*. +\f[] +.fi +.SS Strikeout +.PP +\f[I]Pandoc extension\f[]. +.PP +To strikeout a section of text with a horizontal line, begin and end it +with \f[C]~~\f[]. +Thus, for example, +.IP +.nf +\f[C] +This\ ~~is\ deleted\ text.~~ +\f[] +.fi +.SS Superscripts and subscripts +.PP +\f[I]Pandoc extension\f[]. +.PP +Superscripts may be written by surrounding the superscripted text by +\f[C]^\f[] characters; subscripts may be written by surrounding the +subscripted text by \f[C]~\f[] characters. +Thus, for example, +.IP +.nf +\f[C] +H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024. +\f[] +.fi +.PP +If the superscripted or subscripted text contains spaces, these spaces +must be escaped with backslashes. +(This is to prevent accidental superscripting and subscripting through +the ordinary use of \f[C]~\f[] and \f[C]^\f[].) + Thus, if you want the letter P with \[aq]a cat\[aq] in subscripts, use +\f[C]P~a\\\ cat~\f[], not \f[C]P~a\ cat~\f[]. +.SS Verbatim +.PP +To make a short span of text verbatim, put it inside backticks: +.IP +.nf +\f[C] +What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`? +\f[] +.fi +.PP +If the verbatim text includes a backtick, use double backticks: +.IP +.nf +\f[C] +Here\ is\ a\ literal\ backtick\ ``\ `\ ``. +\f[] +.fi +.PP +(The spaces after the opening backticks and before the closing backticks +will be ignored.) +.PP +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 +in verbatim contexts: +.IP +.nf +\f[C] +This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`. +\f[] +.fi +.SH MATH +.PP +\f[I]Pandoc extension\f[]. +.PP +Anything between two \f[C]$\f[] characters will be treated as TeX math. +The opening \f[C]$\f[] must have a character immediately to its right, +while the closing \f[C]$\f[] must have a character immediately to its +left. +Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math. +If for some reason you need to enclose text in literal \f[C]$\f[] +characters, backslash-escape them and they won\[aq]t be treated as math +delimiters. +.PP +TeX math will be printed in all output formats. +How it is rendered depends on the output format: +.TP +.B Markdown, reStructuredText, LaTeX, 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. +.RS +.RE +.TP +.B Texinfo +It will be rendered inside a \f[C]\@math\f[] command. +.RS +.RE +.TP +.B groff man +It will be rendered verbatim without \f[C]$\f[]\[aq]s. +.RS +.RE +.TP +.B MediaWiki +It will be rendered inside \f[C]\f[] tags. +.RS +.RE +.TP +.B Textile +It will be rendered inside \f[C]\f[] tags. +.RS +.RE +.TP +.B RTF, Docbook, OpenDocument, ODT +It will be rendered, if possible, using unicode characters, and will +otherwise appear verbatim. +.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. +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 +If the \f[C]--latexmathml\f[] option is used, TeX math will be displayed +between $ or $$ characters and put in \f[C]\f[] tags with class +\f[C]LaTeX\f[]. +The LaTeXMathML script will be used to render it as formulas. +(This trick does not work in all browsers, but it works in Firefox. +In browsers that do not support LaTeXMathML, TeX math will appear +verbatim between $ characters.) +.IP "3." 3 +If the \f[C]--jsmath\f[] option is used, TeX math will be put inside +\f[C]\f[] tags (for inline math) or \f[C]

\f[] tags (for +display math) with class \f[C]math\f[]. +The jsMath script will be used to render it. +.IP "4." 3 +If the \f[C]--mimetex\f[] option is used, the mimeTeX CGI script will be +called to generate images for each TeX formula. +This should work in all browsers. +The \f[C]--mimetex\f[] option takes an optional URL as argument. +If no URL is specified, it will be assumed that the mimeTeX CGI script +is at \f[C]/cgi-bin/mimetex.cgi\f[]. +.IP "5." 3 +If the \f[C]--gladtex\f[] option is used, TeX formulas will be enclosed +in \f[C]\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. +So, the procedure is: +.RS 4 +.IP +.nf +\f[C] +pandoc\ -s\ --gladtex\ myfile.txt\ -o\ myfile.htex +gladtex\ -d\ myfile-images\ myfile.htex +#\ produces\ myfile.html\ and\ images\ in\ myfile-images +\f[] +.fi +.RE +.IP "6." 3 +If the \f[C]--webtex\f[] option is used, TeX formulas will be converted +to \f[C]\f[] tags that link to an external script that converts +formulas to images. +The formula will be URL-encoded and concatenated with the URL provided. +If no URL is specified, the Google Chart API will be used +(\f[C]http://chart.apis.google.com/chart?cht=tx&chl=\f[]). +.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). +.PP +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 +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 +(for example), \f[C]*\f[] does not signify emphasis. +.PP +Pandoc behaves this way when \f[C]--strict\f[] is specified; but by +default, pandoc interprets material between HTML block tags as markdown. +Thus, for example, Pandoc will turn +.IP +.nf +\f[C] + +\ +\ \ +\ \ +\ +
*one*[a\ link](http://google.com)
+\f[] +.fi +.PP +into +.IP +.nf +\f[C] + +\ +\ \ +\ \ +\ +
onea\ link
+\f[] +.fi +.PP +whereas \f[C]Markdown.pl\f[] will preserve it as is. +.PP +There is one exception to this rule: text between \f[C]