From 8c588a98c6a0b09a70422cd3a583cc707e199418 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sun, 23 Oct 2011 18:26:50 -0700 Subject: Revert "Added built man pages to repository." This reverts commit eac1fc3750923698db82011b9fda5a0788dfcfea. --- man/man5/pandoc_markdown.5 | 1726 -------------------------------------------- 1 file changed, 1726 deletions(-) delete mode 100644 man/man5/pandoc_markdown.5 (limited to 'man/man5') 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]
\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]