diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | man/man1/markdown2pdf.1 | 170 | ||||
| -rw-r--r-- | man/man1/pandoc.1 | 971 | ||||
| -rw-r--r-- | man/man5/pandoc_markdown.5 | 1726 | ||||
| -rw-r--r-- | pandoc.cabal | 2 |
5 files changed, 3 insertions, 2868 deletions
diff --git a/.gitignore b/.gitignore index 710a6aa3a..df51012fa 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,8 @@ 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 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/pandoc.1 b/man/man1/pandoc.1 deleted file mode 100644 index 04e8b3469..000000000 --- a/man/man1/pandoc.1 +++ /dev/null @@ -1,971 +0,0 @@ -.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]<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 -.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]<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]--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]<body>\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]</body>\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] -\ <dc:rights>Creative\ Commons</dc:rights> -\ <dc:language>es-AR</dc:language> -\f[] -.fi -.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). -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>$title$</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)$ -<meta\ name="author"\ content="$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 - --------------------------- - - -\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 <http://johnmacfarlane.net/pandoc/>. diff --git a/man/man5/pandoc_markdown.5 b/man/man5/pandoc_markdown.5 deleted file mode 100644 index f7a4e22f7..000000000 --- a/man/man5/pandoc_markdown.5 +++ /dev/null @@ -1,1726 +0,0 @@ -.\"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]<div>\f[] (or \f[C]<section>\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] -<pre\ class="haskell"> -\ \ <code> -\ \ ... -\ \ </code> -</pre> -\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]<p>\f[] tags -around "First", "Second", or "Third"), while markdown puts \f[C]<p>\f[] -tags around "Second" and "Third" (but not "First"), because of the blank -space around "Third". -Pandoc follows a simple rule: if the text is followed by a blank line, -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 - -<!--\ end\ of\ list\ --> - -\ \ \ \ {\ 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] -<em>*hello*</em> -\f[] -.fi -.PP -instead of -.IP -.nf -\f[C] -<strong>hello</strong> -\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]<br\ />\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]<math>\f[] tags. -.RS -.RE -.TP -.B Textile -It will be rendered inside \f[C]<span\ class="math">\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]<span>\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]<span>\f[] tags (for inline math) or \f[C]<div>\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]<eq>\f[] tags in the HTML output. -The resulting \f[C]htex\f[] file may then be processed by gladTeX, which -will produce image files for each formula and an \f[C]html\f[] file with -links to these images. -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]<img>\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] -<table> -\ <tr> -\ \ <td>*one*</td> -\ \ <td>[a\ link](http://google.com)</td> -\ </tr> -</table> -\f[] -.fi -.PP -into -.IP -.nf -\f[C] -<table> -\ <tr> -\ \ <td><em>one</em></td> -\ \ <td><a\ href="http://google.com">a\ link</a></td> -\ </tr> -</table> -\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]<script>\f[] and -\f[C]<style>\f[] tags is not interpreted as markdown. -.PP -This departure from standard markdown should make it easier to mix -markdown with HTML block elements. -For example, one can surround a block of markdown text with -\f[C]<div>\f[] tags without preventing it from being interpreted as -markdown. -.SH RAW TEX -.PP -\f[I]Pandoc extension\f[]. -.PP -In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be -included in a document. -Inline TeX commands will be preserved and passed unchanged to the LaTeX -and ConTeXt writers. -Thus, for example, you can use LaTeX to include BibTeX citations: -.IP -.nf -\f[C] -This\ result\ was\ proved\ in\ \\cite{jones.1967}. -\f[] -.fi -.PP -Note that in LaTeX environments, like -.IP -.nf -\f[C] -\\begin{tabular}{|l|l|}\\hline -Age\ &\ Frequency\ \\\\\ \\hline -18--25\ \ &\ 15\ \\\\ -26--35\ \ &\ 33\ \\\\\ -36--45\ \ &\ 22\ \\\\\ \\hline -\\end{tabular} -\f[] -.fi -.PP -the material between the begin and end tags will be interpreted as raw -LaTeX, not as markdown. -.PP -Inline LaTeX is ignored in output formats other than Markdown, LaTeX, -and ConTeXt. -.SS Macros -.PP -For output formats other than LaTeX, pandoc will parse LaTeX -\f[C]\\newcommand\f[] and \f[C]\\renewcommand\f[] definitions and apply -the resulting macros to all LaTeX math. -So, for example, the following will work in all output formats, not just -LaTeX: -.IP -.nf -\f[C] -\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle} - -$\\tuple{a,\ b,\ c}$ -\f[] -.fi -.PP -In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be -passed unchanged to the output. -.SH LINKS -.PP -Markdown allows links to be specified in several ways. -.SS Automatic links -.PP -If you enclose a URL or email address in pointy brackets, it will become -a link: -.IP -.nf -\f[C] -<http://google.com> -<sam\@green.eggs.ham> -\f[] -.fi -.SS Inline links -.PP -An inline link consists of the link text in square brackets, followed by -the URL in parentheses. -(Optionally, the URL can be followed by a link title, in quotes.) -.IP -.nf -\f[C] -This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with -a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!"). -\f[] -.fi -.PP -There can be no space between the bracketed part and the parenthesized -part. -The link text can contain formatting (such as emphasis), but the title -cannot. -.SS Reference links -.PP -An \f[I]explicit\f[] reference link has two parts, the link itself and -the link definition, which may occur elsewhere in the document (either -before or after the link). -.PP -The link consists of link text in square brackets, followed by a label -in square brackets. -(There can be space between the two.) - The link definition must begin at the left margin or indented no more -than three spaces. -It consists of the bracketed label, followed by a colon and a space, -followed by the URL, and optionally (after a space) a link title either -in quotes or in parentheses. -.PP -Here are some examples: -.IP -.nf -\f[C] -[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional" -[my\ label\ 2]:\ /foo -[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation) -[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq] -\f[] -.fi -.PP -The URL may optionally be surrounded by angle brackets: -.IP -.nf -\f[C] -[my\ label\ 5]:\ <http://foo.bar.baz> -\f[] -.fi -.PP -The title may go on the next line: -.IP -.nf -\f[C] -[my\ label\ 3]:\ http://fsf.org -\ \ "The\ free\ software\ foundation" -\f[] -.fi -.PP -Note that link labels are not case sensitive. -So, this will work: -.IP -.nf -\f[C] -Here\ is\ [my\ link][FOO] - -[Foo]:\ /bar/baz -\f[] -.fi -.PP -In an \f[I]implicit\f[] reference link, the second pair of brackets is -empty, or omitted entirely: -.IP -.nf -\f[C] -See\ [my\ website][],\ or\ [my\ website]. - -[my\ website]:\ http://foo.bar.baz -\f[] -.fi -.SH IMAGES -.PP -A link immediately preceded by a \f[C]!\f[] will be treated as an image. -The link text will be used as the image\[aq]s alt text: -.IP -.nf -\f[C] - - -![movie\ reel] - -[movie\ reel]:\ movie.gif -\f[] -.fi -.SS Pictures with captions -.PP -\f[I]Pandoc extension\f[]. -.PP -An image occurring by itself in a paragraph will be rendered as a figure -with a caption.[4] (In LaTeX, a figure environment will be used; in -HTML, the image will be placed in a \f[C]div\f[] with class -\f[C]figure\f[], together with a caption in a \f[C]p\f[] with class -\f[C]caption\f[].) - The image\[aq]s alt text will be used as the caption. -.IP -.nf -\f[C] - -\f[] -.fi -.PP -If you just want a regular inline image, just make sure it is not the -only thing in the paragraph. -One way to do this is to insert a nonbreaking space after the image: -.IP -.nf -\f[C] -![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\ -\f[] -.fi -.SH FOOTNOTES -.PP -\f[I]Pandoc extension\f[]. -.PP -Pandoc\[aq]s markdown allows footnotes, using the following syntax: -.IP -.nf -\f[C] -Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote] - -[^1]:\ Here\ is\ the\ footnote. - -[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks. - -\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they\ -belong\ to\ the\ previous\ footnote. - -\ \ \ \ \ \ \ \ {\ some.code\ } - -\ \ \ \ The\ whole\ paragraph\ can\ be\ indented,\ or\ just\ the\ first -\ \ \ \ line.\ \ In\ this\ way,\ multi-paragraph\ footnotes\ work\ like -\ \ \ \ multi-paragraph\ list\ items. - -This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it -isn\[aq]t\ indented. -\f[] -.fi -.PP -The identifiers in footnote references may not contain spaces, tabs, or -newlines. -These identifiers are used only to correlate the footnote reference with -the note itself; in the output, footnotes will be numbered sequentially. -.PP -The footnotes themselves need not be placed at the end of the document. -They may appear anywhere except inside other block elements (lists, -block quotes, tables, etc.) -\&. -.PP -Inline footnotes are also allowed (though, unlike regular notes, they -cannot contain multiple paragraphs). -The syntax is as follows: -.IP -.nf -\f[C] -Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since -you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the -note.] -\f[] -.fi -.PP -Inline and regular footnotes may be mixed freely. -.SH CITATIONS -.PP -\f[I]Pandoc extension\f[]. -.PP -Pandoc can automatically generate citations and a bibliography in a -number of styles (using Andrea Rossato\[aq]s \f[C]hs-citeproc\f[]). -In order to use this feature, you will need a bibliographic database in -one of the following formats: -.PP -.TS -tab(@); -l l. -T{ -Format -T}@T{ -File extension -T} -_ -T{ -MODS -T}@T{ -\&.mods -T} -T{ -BibTeX/BibLaTeX -T}@T{ -\&.bib -T} -T{ -RIS -T}@T{ -\&.ris -T} -T{ -EndNote -T}@T{ -\&.enl -T} -T{ -EndNote XML -T}@T{ -\&.xml -T} -T{ -ISI -T}@T{ -\&.wos -T} -T{ -MEDLINE -T}@T{ -\&.medline -T} -T{ -Copac -T}@T{ -\&.copac -T} -T{ -JSON citeproc -T}@T{ -\&.json -T} -.TE -.PP -You will need to specify the bibliography file using the -\f[C]--bibliography\f[] command-line option (which may be repeated if -you have several bibliographies). -.PP -By default, pandoc will use a Chicago author-date format for citations -and references. -To use another style, you will need to use the \f[C]--csl\f[] option to -specify a CSL 1.0 style file. -A primer on creating and modifying CSL styles can be found at -\f[C]http://citationstyles.org/downloads/primer.html\f[]. -A repository of CSL styles can be found at -\f[C]https://github.com/citation-style-language/styles\f[]. -See also \f[C]http://zotero.org/styles\f[] for easy browsing. -.PP -Citations go inside square brackets and are separated by semicolons. -Each citation must have a key, composed of \[aq]\@\[aq] + the citation -identifier from the database, and may optionally have a prefix, a -locator, and a suffix. -Here are some examples: -.IP -.nf -\f[C] -Blah\ blah\ [see\ \@doe99,\ pp.\ 33-35;\ also\ \@smith04,\ ch.\ 1]. - -Blah\ blah\ [\@doe99,\ pp.\ 33-35,\ 38-39\ and\ *passim*]. - -Blah\ blah\ [\@smith04;\ \@doe99]. -\f[] -.fi -.PP -A minus sign (\f[C]-\f[]) before the \f[C]\@\f[] will suppress mention -of the author in the citation. -This can be useful when the author is already mentioned in the text: -.IP -.nf -\f[C] -Smith\ says\ blah\ [-\@smith04]. -\f[] -.fi -.PP -You can also write an in-text citation, as follows: -.IP -.nf -\f[C] -\@smith04\ says\ blah. - -\@smith04\ [p.\ 33]\ says\ blah. -\f[] -.fi -.PP -If the style calls for a list of works cited, it will be placed at the -end of the document. -Normally, you will want to end your document with an appropriate header: -.IP -.nf -\f[C] -last\ paragraph... - -#\ References -\f[] -.fi -.PP -The bibliography will be inserted after this header. -.SH NOTES -.SS [1] -.PP -The point of this rule is to ensure that normal paragraphs starting with -people\[aq]s initials, like -.IP -.nf -\f[C] -B.\ Russell\ was\ an\ English\ philosopher. -\f[] -.fi -.PP -do not get treated as list items. -.PP -This rule will not prevent -.IP -.nf -\f[C] -(C)\ 2007\ Joe\ Smith -\f[] -.fi -.PP -from being interpreted as a list item. -In this case, a backslash escape can be used: -.IP -.nf -\f[C] -(C\\)\ 2007\ Joe\ Smith -\f[] -.fi -.SS [2] -.PP -I have also been influenced by the suggestions of David Wheeler. -.SS [3] -.PP -This scheme is due to Michel Fortin, who proposed it on the Markdown -discussion list. -.SS [4] -.PP -This feature is not yet implemented for RTF, OpenDocument, or ODT. -In those formats, you\[aq]ll just get an image in a paragraph by itself, -with no caption. -.SH SEE ALSO -.PP -\f[C]pandoc\f[] (1). diff --git a/pandoc.cabal b/pandoc.cabal index feab0d6f8..a74febfea 100644 --- a/pandoc.cabal +++ b/pandoc.cabal @@ -75,7 +75,7 @@ Extra-Source-Files: MakeManPage.hs, man/man1/pandoc.1.template, man/man5/pandoc_markdown.5.template, - -- generated man pages + -- generated man pages (produced post-build) man/man1/markdown2pdf.1, man/man1/pandoc.1, man/man5/pandoc_markdown.5, |