@@ -0,0 +1,1726 @@
1+.\"t
2+.TH PANDOC_MARKDOWN 5 "July 30, 2011" "Pandoc"
3+.SH NAME
4+pandoc_markdown - markdown syntax for pandoc(1)
5+.SH DESCRIPTION
6+.PP
7+Pandoc understands an extended and slightly revised version of John
8+Gruber\[aq]s markdown syntax.
9+This document explains the syntax, noting differences from standard
10+markdown.
11+Except where noted, these differences can be suppressed by specifying
12+the \f[C]--strict\f[] command-line option.
13+.SH PHILOSOPHY
14+.PP
15+Markdown is designed to be easy to write, and, even more importantly,
16+easy to read:
17+.RS
18+.PP
19+A Markdown-formatted document should be publishable as-is, as plain
20+text, without looking like it\[aq]s been marked up with tags or
21+formatting instructions.
22+-- John Gruber
23+.RE
24+.PP
25+This principle has guided pandoc\[aq]s decisions in finding syntax for
26+tables, footnotes, and other extensions.
27+.PP
28+There is, however, one respect in which pandoc\[aq]s aims are different
29+from the original aims of markdown.
30+Whereas markdown was originally designed with HTML generation in mind,
31+pandoc is designed for multiple output formats.
32+Thus, while pandoc allows the embedding of raw HTML, it discourages it,
33+and provides other, non-HTMLish ways of representing important document
34+elements like definition lists, tables, mathematics, and footnotes.
35+.SH PARAGRAPHS
36+.PP
37+A paragraph is one or more lines of text followed by one or more blank
38+line.
39+Newlines are treated as spaces, so you can reflow your paragraphs as you
40+like.
41+If you need a hard line break, put two or more spaces at the end of a
42+line, or type a backslash followed by a newline.
43+.SH HEADERS
44+.PP
45+There are two kinds of headers, Setext and atx.
46+.SS Setext-style headers
47+.PP
48+A setext-style header is a line of text "underlined" with a row of
49+\f[C]=\f[] signs (for a level one header) of \f[C]-\f[] signs (for a
50+level two header):
51+.IP
52+.nf
53+\f[C]
54+A\ level-one\ header
55+==================
56+
57+A\ level-two\ header
58+------------------
59+\f[]
60+.fi
61+.PP
62+The header text can contain inline formatting, such as emphasis (see
63+Inline formatting, below).
64+.SS Atx-style headers
65+.PP
66+An Atx-style header consists of one to six \f[C]#\f[] signs and a line
67+of text, optionally followed by any number of \f[C]#\f[] signs.
68+The number of \f[C]#\f[] signs at the beginning of the line is the
69+header level:
70+.IP
71+.nf
72+\f[C]
73+##\ A\ level-two\ header
74+
75+###\ A\ level-three\ header\ ###
76+\f[]
77+.fi
78+.PP
79+As with setext-style headers, the header text can contain formatting:
80+.IP
81+.nf
82+\f[C]
83+#\ A\ level-one\ header\ with\ a\ [link](/url)\ and\ *emphasis*
84+\f[]
85+.fi
86+.PP
87+Standard markdown syntax does not require a blank line before a header.
88+Pandoc does require this (except, of course, at the beginning of the
89+document).
90+The reason for the requirement is that it is all too easy for a
91+\f[C]#\f[] to end up at the beginning of a line by accident (perhaps
92+through line wrapping).
93+Consider, for example:
94+.IP
95+.nf
96+\f[C]
97+I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
98+#22,\ for\ example,\ and\ #5.
99+\f[]
100+.fi
101+.SS Header identifiers in HTML
102+.PP
103+\f[I]Pandoc extension\f[].
104+.PP
105+Each header element in pandoc\[aq]s HTML output is given a unique
106+identifier.
107+This identifier is based on the text of the header.
108+To derive the identifier from the header text,
109+.IP \[bu] 2
110+Remove all formatting, links, etc.
111+.IP \[bu] 2
112+Remove all punctuation, except underscores, hyphens, and periods.
113+.IP \[bu] 2
114+Replace all spaces and newlines with hyphens.
115+.IP \[bu] 2
116+Convert all alphabetic characters to lowercase.
117+.IP \[bu] 2
118+Remove everything up to the first letter (identifiers may not begin with
119+a number or punctuation mark).
120+.IP \[bu] 2
121+If nothing is left after this, use the identifier \f[C]section\f[].
122+.PP
123+Thus, for example,
124+.PP
125+.TS
126+tab(@);
127+l l.
128+T{
129+Header
130+T}@T{
131+Identifier
132+T}
133+_
134+T{
135+Header identifiers in HTML
136+T}@T{
137+\f[C]header-identifiers-in-html\f[]
138+T}
139+T{
140+\f[I]Dogs\f[]?--in \f[I]my\f[] house?
141+T}@T{
142+\f[C]dogs--in-my-house\f[]
143+T}
144+T{
145+HTML, S5, or RTF?
146+T}@T{
147+\f[C]html-s5-or-rtf\f[]
148+T}
149+T{
150+3.
151+Applications
152+T}@T{
153+\f[C]applications\f[]
154+T}
155+T{
156+33
157+T}@T{
158+\f[C]section\f[]
159+T}
160+.TE
161+.PP
162+These rules should, in most cases, allow one to determine the identifier
163+from the header text.
164+The exception is when several headers have the same text; in this case,
165+the first will get an identifier as described above; the second will get
166+the same identifier with \f[C]-1\f[] appended; the third with
167+\f[C]-2\f[]; and so on.
168+.PP
169+These identifiers are used to provide link targets in the table of
170+contents generated by the \f[C]--toc|--table-of-contents\f[] option.
171+They also make it easy to provide links from one section of a document
172+to another.
173+A link to this section, for example, might look like this:
174+.IP
175+.nf
176+\f[C]
177+See\ the\ section\ on
178+[header\ identifiers](#header-identifiers-in-html).
179+\f[]
180+.fi
181+.PP
182+Note, however, that this method of providing links to sections works
183+only in HTML.
184+.PP
185+If the \f[C]--section-divs\f[] option is specified, then each section
186+will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if
187+\f[C]--html5\f[] was specified), and the identifier will be attached to
188+the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than the
189+header itself.
190+This allows entire sections to be manipulated using javascript or
191+treated differently in CSS.
192+.SH BLOCK QUOTATIONS
193+.PP
194+Markdown uses email conventions for quoting blocks of text.
195+A block quotation is one or more paragraphs or other block elements
196+(such as lists or headers), with each line preceded by a \f[C]>\f[]
197+character and a space.
198+(The \f[C]>\f[] need not start at the left margin, but it should not be
199+indented more than three spaces.)
200+.IP
201+.nf
202+\f[C]
203+>\ This\ is\ a\ block\ quote.\ This
204+>\ paragraph\ has\ two\ lines.
205+>
206+>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
207+>\ 2.\ Second\ item.
208+\f[]
209+.fi
210+.PP
211+A "lazy" form, which requires the \f[C]>\f[] character only on the first
212+line of each block, is also allowed:
213+.IP
214+.nf
215+\f[C]
216+>\ This\ is\ a\ block\ quote.\ This
217+paragraph\ has\ two\ lines.
218+
219+>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
220+2.\ Second\ item.
221+\f[]
222+.fi
223+.PP
224+Among the block elements that can be contained in a block quote are
225+other block quotes.
226+That is, block quotes can be nested:
227+.IP
228+.nf
229+\f[C]
230+>\ This\ is\ a\ block\ quote.
231+>
232+>\ >\ A\ block\ quote\ within\ a\ block\ quote.
233+\f[]
234+.fi
235+.PP
236+Standard markdown syntax does not require a blank line before a block
237+quote.
238+Pandoc does require this (except, of course, at the beginning of the
239+document).
240+The reason for the requirement is that it is all too easy for a
241+\f[C]>\f[] to end up at the beginning of a line by accident (perhaps
242+through line wrapping).
243+So, unless \f[C]--strict\f[] is used, the following does not produce a
244+nested block quote in pandoc:
245+.IP
246+.nf
247+\f[C]
248+>\ This\ is\ a\ block\ quote.
249+>>\ Nested.
250+\f[]
251+.fi
252+.SH VERBATIM (CODE) BLOCKS
253+.SS Indented code blocks
254+.PP
255+A block of text indented four spaces (or one tab) is treated as verbatim
256+text: that is, special characters do not trigger special formatting, and
257+all spaces and line breaks are preserved.
258+For example,
259+.IP
260+.nf
261+\f[C]
262+\ \ \ \ if\ (a\ >\ 3)\ {
263+\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN);
264+\ \ \ \ }
265+\f[]
266+.fi
267+.PP
268+The initial (four space or one tab) indentation is not considered part
269+of the verbatim text, and is removed in the output.
270+.PP
271+Note: blank lines in the verbatim text need not begin with four spaces.
272+.SS Delimited code blocks
273+.PP
274+\f[I]Pandoc extension\f[].
275+.PP
276+In addition to standard indented code blocks, Pandoc supports
277+\f[I]delimited\f[] code blocks.
278+These begin with a row of three or more tildes (\f[C]~\f[]) and end with
279+a row of tildes that must be at least as long as the starting row.
280+Everything between the tilde-lines is treated as code.
281+No indentation is necessary:
282+.IP
283+.nf
284+\f[C]
285+~~~~~~~
286+if\ (a\ >\ 3)\ {
287+\ \ moveShip(5\ *\ gravity,\ DOWN);
288+}
289+~~~~~~~
290+\f[]
291+.fi
292+.PP
293+Like regular code blocks, delimited code blocks must be separated from
294+surrounding text by blank lines.
295+.PP
296+If the code itself contains a row of tildes, just use a longer row of
297+tildes at the start and end:
298+.IP
299+.nf
300+\f[C]
301+~~~~~~~~~~~~~~~~
302+~~~~~~~~~~
303+code\ including\ tildes
304+~~~~~~~~~~
305+~~~~~~~~~~~~~~~~
306+\f[]
307+.fi
308+.PP
309+Optionally, you may specify the language of the code block using this
310+syntax:
311+.IP
312+.nf
313+\f[C]
314+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ {.haskell\ .numberLines}
315+qsort\ []\ \ \ \ \ =\ []
316+qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++
317+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)\
318+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
319+\f[]
320+.fi
321+.PP
322+Some output formats can use this information to do syntax highlighting.
323+Currently, the only output format that uses this information is HTML.
324+.PP
325+If pandoc has been compiled with syntax highlighting support, then the
326+code block above will appear highlighted, with numbered lines.
327+(To see which languages are supported, do \f[C]pandoc\ --version\f[].)
328+.PP
329+If pandoc has not been compiled with syntax highlighting support, the
330+code block above will appear as follows:
331+.IP
332+.nf
333+\f[C]
334+<pre\ class="haskell">
335+\ \ <code>
336+\ \ ...
337+\ \ </code>
338+</pre>
339+\f[]
340+.fi
341+.SH LISTS
342+.SS Bullet lists
343+.PP
344+A bullet list is a list of bulleted list items.
345+A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or
346+\f[C]-\f[]).
347+Here is a simple example:
348+.IP
349+.nf
350+\f[C]
351+*\ one
352+*\ two
353+*\ three
354+\f[]
355+.fi
356+.PP
357+This will produce a "compact" list.
358+If you want a "loose" list, in which each item is formatted as a
359+paragraph, put spaces between the items:
360+.IP
361+.nf
362+\f[C]
363+*\ one
364+
365+*\ two
366+
367+*\ three
368+\f[]
369+.fi
370+.PP
371+The bullets need not be flush with the left margin; they may be indented
372+one, two, or three spaces.
373+The bullet must be followed by whitespace.
374+.PP
375+List items look best if subsequent lines are flush with the first line
376+(after the bullet):
377+.IP
378+.nf
379+\f[C]
380+*\ here\ is\ my\ first
381+\ \ list\ item.
382+*\ and\ my\ second.
383+\f[]
384+.fi
385+.PP
386+But markdown also allows a "lazy" format:
387+.IP
388+.nf
389+\f[C]
390+*\ here\ is\ my\ first
391+list\ item.
392+*\ and\ my\ second.
393+\f[]
394+.fi
395+.SS The four-space rule
396+.PP
397+A list item may contain multiple paragraphs and other block-level
398+content.
399+However, subsequent paragraphs must be preceded by a blank line and
400+indented four spaces or a tab.
401+The list will look better if the first paragraph is aligned with the
402+rest:
403+.IP
404+.nf
405+\f[C]
406+\ \ *\ First\ paragraph.
407+
408+\ \ \ \ Continued.
409+
410+\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented
411+\ \ \ \ eight\ spaces:
412+
413+\ \ \ \ \ \ \ \ {\ code\ }
414+\f[]
415+.fi
416+.PP
417+List items may include other lists.
418+In this case the preceding blank line is optional.
419+The nested list must be indented four spaces or one tab:
420+.IP
421+.nf
422+\f[C]
423+*\ fruits
424+\ \ \ \ +\ apples
425+\ \ \ \ \ \ \ \ -\ macintosh
426+\ \ \ \ \ \ \ \ -\ red\ delicious
427+\ \ \ \ +\ pears
428+\ \ \ \ +\ peaches
429+*\ vegetables
430+\ \ \ \ +\ brocolli
431+\ \ \ \ +\ chard
432+\f[]
433+.fi
434+.PP
435+As noted above, markdown allows you to write list items "lazily,"
436+instead of indenting continuation lines.
437+However, if there are multiple paragraphs or other blocks in a list
438+item, the first line of each must be indented.
439+.IP
440+.nf
441+\f[C]
442++\ A\ lazy,\ lazy,\ list
443+item.
444+
445++\ Another\ one;\ this\ looks
446+bad\ but\ is\ legal.
447+
448+\ \ \ \ Second\ paragraph\ of\ second
449+list\ item.
450+\f[]
451+.fi
452+.PP
453+\f[B]Note:\f[] Although the four-space rule for continuation paragraphs
454+comes from the official markdown syntax guide, the reference
455+implementation, \f[C]Markdown.pl\f[], does not follow it.
456+So pandoc will give different results than \f[C]Markdown.pl\f[] when
457+authors have indented continuation paragraphs fewer than four spaces.
458+.PP
459+The markdown syntax guide is not explicit whether the four-space rule
460+applies to \f[I]all\f[] block-level content in a list item; it only
461+mentions paragraphs and code blocks.
462+But it implies that the rule applies to all block-level content
463+(including nested lists), and pandoc interprets it that way.
464+.SS Ordered lists
465+.PP
466+Ordered lists work just like bulleted lists, except that the items begin
467+with enumerators rather than bullets.
468+.PP
469+In standard markdown, enumerators are decimal numbers followed by a
470+period and a space.
471+The numbers themselves are ignored, so there is no difference between
472+this list:
473+.IP
474+.nf
475+\f[C]
476+1.\ \ one
477+2.\ \ two
478+3.\ \ three
479+\f[]
480+.fi
481+.PP
482+and this one:
483+.IP
484+.nf
485+\f[C]
486+5.\ \ one
487+7.\ \ two
488+1.\ \ three
489+\f[]
490+.fi
491+.PP
492+\f[I]Pandoc extension\f[].
493+.PP
494+Unlike standard markdown, Pandoc allows ordered list items to be marked
495+with uppercase and lowercase letters and roman numerals, in addition to
496+arabic numerals.
497+List markers may be enclosed in parentheses or followed by a single
498+right-parentheses or period.
499+They must be separated from the text that follows by at least one space,
500+and, if the list marker is a capital letter with a period, by at least
501+two spaces.[1]
502+.PP
503+Pandoc also pays attention to the type of list marker used, and to the
504+starting number, and both of these are preserved where possible in the
505+output format.
506+Thus, the following yields a list with numbers followed by a single
507+parenthesis, starting with 9, and a sublist with lowercase roman
508+numerals:
509+.IP
510+.nf
511+\f[C]
512+\ 9)\ \ Ninth
513+10)\ \ Tenth
514+11)\ \ Eleventh
515+\ \ \ \ \ \ \ i.\ subone
516+\ \ \ \ \ \ ii.\ subtwo
517+\ \ \ \ \ iii.\ subthree
518+\f[]
519+.fi
520+.PP
521+Note that Pandoc pays attention only to the \f[I]starting\f[] marker in
522+a list.
523+So, the following yields a list numbered sequentially starting from 2:
524+.IP
525+.nf
526+\f[C]
527+(2)\ Two
528+(5)\ Three
529+1.\ \ Four
530+*\ \ \ Five
531+\f[]
532+.fi
533+.PP
534+If default list markers are desired, use \f[C]#.\f[]:
535+.IP
536+.nf
537+\f[C]
538+#.\ \ one
539+#.\ \ two
540+#.\ \ three
541+\f[]
542+.fi
543+.SS Definition lists
544+.PP
545+\f[I]Pandoc extension\f[].
546+.PP
547+Pandoc supports definition lists, using a syntax inspired by PHP
548+Markdown Extra and reStructuredText:[2]
549+.IP
550+.nf
551+\f[C]
552+Term\ 1
553+
554+:\ \ \ Definition\ 1
555+
556+Term\ 2\ with\ *inline\ markup*
557+
558+:\ \ \ Definition\ 2
559+
560+\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ }
561+
562+\ \ \ \ Third\ paragraph\ of\ definition\ 2.
563+\f[]
564+.fi
565+.PP
566+Each term must fit on one line, which may optionally be followed by a
567+blank line, and must be followed by one or more definitions.
568+A definition begins with a colon or tilde, which may be indented one or
569+two spaces.
570+A term may have multiple definitions, and each definition may consist of
571+one or more block elements (paragraph, code block, list, etc.)
572+, each indented four spaces or one tab stop.
573+.PP
574+If you leave space after the definition (as in the example above), the
575+blocks of the definitions will be considered paragraphs.
576+In some output formats, this will mean greater spacing between
577+term/definition pairs.
578+For a compact definition list, do not leave space between the definition
579+and the next term:
580+.IP
581+.nf
582+\f[C]
583+Term\ 1
584+\ \ ~\ Definition\ 1
585+Term\ 2
586+\ \ ~\ Definition\ 2a
587+\ \ ~\ Definition\ 2b
588+\f[]
589+.fi
590+.SS Numbered example lists
591+.PP
592+\f[I]Pandoc extension\f[].
593+.PP
594+The special list marker \f[C]\@\f[] can be used for sequentially
595+numbered examples.
596+The first list item with a \f[C]\@\f[] marker will be numbered
597+\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
598+The numbered examples need not occur in a single list; each new list
599+using \f[C]\@\f[] will take up where the last stopped.
600+So, for example:
601+.IP
602+.nf
603+\f[C]
604+(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1).
605+(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2).
606+
607+Explanation\ of\ examples.
608+
609+(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3).
610+\f[]
611+.fi
612+.PP
613+Numbered examples can be labeled and referred to elsewhere in the
614+document:
615+.IP
616+.nf
617+\f[C]
618+(\@good)\ \ This\ is\ a\ good\ example.
619+
620+As\ (\@good)\ illustrates,\ ...
621+\f[]
622+.fi
623+.PP
624+The label can be any string of alphanumeric characters, underscores, or
625+hyphens.
626+.SS Compact and loose lists
627+.PP
628+Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge
629+cases" involving lists.
630+Consider this source:
631+.IP
632+.nf
633+\f[C]
634++\ \ \ First
635++\ \ \ Second:
636+\ -\ \ \ Fee
637+\ -\ \ \ Fie
638+\ -\ \ \ Foe
639+
640++\ \ \ Third
641+\f[]
642+.fi
643+.PP
644+Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags
645+around "First", "Second", or "Third"), while markdown puts \f[C]<p>\f[]
646+tags around "Second" and "Third" (but not "First"), because of the blank
647+space around "Third".
648+Pandoc follows a simple rule: if the text is followed by a blank line,
649+it is treated as a paragraph.
650+Since "Second" is followed by a list, and not a blank line, it isn\[aq]t
651+treated as a paragraph.
652+The fact that the list is followed by a blank line is irrelevant.
653+(Note: Pandoc works this way even when the \f[C]--strict\f[] option is
654+specified.
655+This behavior is consistent with the official markdown syntax
656+description, even though it is different from that of
657+\f[C]Markdown.pl\f[].)
658+.SS Ending a list
659+.PP
660+What if you want to put an indented code block after a list?
661+.IP
662+.nf
663+\f[C]
664+-\ \ \ item\ one
665+-\ \ \ item\ two
666+
667+\ \ \ \ {\ my\ code\ block\ }
668+\f[]
669+.fi
670+.PP
671+Trouble! Here pandoc (like other markdown implementations) will treat
672+\f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and
673+not as a code block.
674+.PP
675+To "cut off" the list after item two, you can insert some non-indented
676+content, like an HTML comment, which won\[aq]t produce visible output in
677+any format:
678+.IP
679+.nf
680+\f[C]
681+-\ \ \ item\ one
682+-\ \ \ item\ two
683+
684+<!--\ end\ of\ list\ -->
685+
686+\ \ \ \ {\ my\ code\ block\ }
687+\f[]
688+.fi
689+.PP
690+You can use the same trick if you want two consecutive lists instead of
691+one big list:
692+.IP
693+.nf
694+\f[C]
695+1.\ \ one
696+2.\ \ two
697+3.\ \ three
698+
699+<!--\ -->
700+
701+a.\ \ uno
702+b.\ \ dos
703+c.\ \ tres
704+\f[]
705+.fi
706+.SH HORIZONTAL RULES
707+.PP
708+A line containing a row of three or more \f[C]*\f[], \f[C]-\f[], or
709+\f[C]_\f[] characters (optionally separated by spaces) produces a
710+horizontal rule:
711+.IP
712+.nf
713+\f[C]
714+*\ \ *\ \ *\ \ *
715+
716+---------------
717+\f[]
718+.fi
719+.SH TABLES
720+.PP
721+\f[I]Pandoc extension\f[].
722+.PP
723+Three kinds of tables may be used.
724+All three kinds presuppose the use of a fixed-width font, such as
725+Courier.
726+.PP
727+\f[B]Simple tables\f[] look like this:
728+.IP
729+.nf
730+\f[C]
731+\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default
732+-------\ \ \ \ \ ------\ ----------\ \ \ -------
733+\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12
734+\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123
735+\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1
736+
737+Table:\ \ Demonstration\ of\ simple\ table\ syntax.
738+\f[]
739+.fi
740+.PP
741+The headers and table rows must each fit on one line.
742+Column alignments are determined by the position of the header text
743+relative to the dashed line below it:[3]
744+.IP \[bu] 2
745+If the dashed line is flush with the header text on the right side but
746+extends beyond it on the left, the column is right-aligned.
747+.IP \[bu] 2
748+If the dashed line is flush with the header text on the left side but
749+extends beyond it on the right, the column is left-aligned.
750+.IP \[bu] 2
751+If the dashed line extends beyond the header text on both sides, the
752+column is centered.
753+.IP \[bu] 2
754+If the dashed line is flush with the header text on both sides, the
755+default alignment is used (in most cases, this will be left).
756+.PP
757+The table must end with a blank line, or a line of dashes followed by a
758+blank line.
759+A caption may optionally be provided (as illustrated in the example
760+above).
761+A caption is a paragraph beginning with the string \f[C]Table:\f[] (or
762+just \f[C]:\f[]), which will be stripped off.
763+It may appear either before or after the table.
764+.PP
765+The column headers may be omitted, provided a dashed line is used to end
766+the table.
767+For example:
768+.IP
769+.nf
770+\f[C]
771+-------\ \ \ \ \ ------\ ----------\ \ \ -------
772+\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12
773+\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123
774+\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1
775+-------\ \ \ \ \ ------\ ----------\ \ \ -------
776+\f[]
777+.fi
778+.PP
779+When headers are omitted, column alignments are determined on the basis
780+of the first line of the table body.
781+So, in the tables above, the columns would be right, left, center, and
782+right aligned, respectively.
783+.PP
784+\f[B]Multiline tables\f[] allow headers and table rows to span multiple
785+lines of text (but cells that span multiple columns or rows of the table
786+are not supported).
787+Here is an example:
788+.IP
789+.nf
790+\f[C]
791+-------------------------------------------------------------
792+\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left
793+\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned
794+-----------\ -------\ ---------------\ -------------------------
795+\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
796+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
797+
798+\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
799+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
800+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
801+-------------------------------------------------------------
802+
803+Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span
804+multiple\ lines.
805+\f[]
806+.fi
807+.PP
808+These work like simple tables, but with the following differences:
809+.IP \[bu] 2
810+They must begin with a row of dashes, before the header text (unless the
811+headers are omitted).
812+.IP \[bu] 2
813+They must end with a row of dashes, then a blank line.
814+.IP \[bu] 2
815+The rows must be separated by blank lines.
816+.PP
817+In multiline tables, the table parser pays attention to the widths of
818+the columns, and the writers try to reproduce these relative widths in
819+the output.
820+So, if you find that one of the columns is too narrow in the output, try
821+widening it in the markdown source.
822+.PP
823+Headers may be omitted in multiline tables as well as simple tables:
824+.IP
825+.nf
826+\f[C]
827+-----------\ -------\ ---------------\ -------------------------
828+\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
829+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
830+
831+\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
832+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
833+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
834+-------------------------------------------------------------
835+
836+:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.
837+\f[]
838+.fi
839+.PP
840+It is possible for a multiline table to have just one row, but the row
841+should be followed by a blank line (and then the row of dashes that ends
842+the table), or the table may be interpreted as a simple table.
843+.PP
844+\f[B]Grid tables\f[] look like this:
845+.IP
846+.nf
847+\f[C]
848+:\ Sample\ grid\ table.
849+
850++---------------+---------------+--------------------+
851+|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ |
852++===============+===============+====================+
853+|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ -\ built-in\ wrapper\ |
854+|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ bright\ color\ \ \ \ \ |
855++---------------+---------------+--------------------+
856+|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ -\ cures\ scurvy\ \ \ \ \ |
857+|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ tasty\ \ \ \ \ \ \ \ \ \ \ \ |
858++---------------+---------------+--------------------+
859+\f[]
860+.fi
861+.PP
862+The row of \f[C]=\f[]s separates the header from the table body, and can
863+be omitted for a headerless table.
864+The cells of grid tables may contain arbitrary block elements (multiple
865+paragraphs, code blocks, lists, etc.)
866+\&.
867+Alignments are not supported, nor are cells that span multiple columns
868+or rows.
869+Grid tables can be created easily using Emacs table mode.
870+.SH TITLE BLOCK
871+.PP
872+\f[I]Pandoc extension\f[].
873+.PP
874+If the file begins with a title block
875+.IP
876+.nf
877+\f[C]
878+%\ title
879+%\ author(s)\ (separated\ by\ semicolons)
880+%\ date
881+\f[]
882+.fi
883+.PP
884+it will be parsed as bibliographic information, not regular text.
885+(It will be used, for example, in the title of standalone LaTeX or HTML
886+output.)
887+ The block may contain just a title, a title and an author, or all three
888+elements.
889+If you want to include an author but no title, or a title and a date but
890+no author, you need a blank line:
891+.IP
892+.nf
893+\f[C]
894+%
895+%\ Author
896+
897+%\ My\ title
898+%
899+%\ June\ 15,\ 2006
900+\f[]
901+.fi
902+.PP
903+The title may occupy multiple lines, but continuation lines must begin
904+with leading space, thus:
905+.IP
906+.nf
907+\f[C]
908+%\ My\ title
909+\ \ on\ multiple\ lines
910+\f[]
911+.fi
912+.PP
913+If a document has multiple authors, the authors may be put on separate
914+lines with leading space, or separated by semicolons, or both.
915+So, all of the following are equivalent:
916+.IP
917+.nf
918+\f[C]
919+%\ Author\ One
920+\ \ Author\ Two
921+
922+%\ Author\ One;\ Author\ Two
923+
924+%\ Author\ One;
925+\ \ Author\ Two
926+\f[]
927+.fi
928+.PP
929+The date must fit on one line.
930+.PP
931+All three metadata fields may contain standard inline formatting
932+(italics, links, footnotes, etc.)
933+\&.
934+.PP
935+Title blocks will always be parsed, but they will affect the output only
936+when the \f[C]--standalone\f[] (\f[C]-s\f[]) option is chosen.
937+In HTML output, titles will appear twice: once in the document head --
938+this is the title that will appear at the top of the window in a browser
939+-- and once at the beginning of the document body.
940+The title in the document head can have an optional prefix attached
941+(\f[C]--title-prefix\f[] or \f[C]-T\f[] option).
942+The title in the body appears as an H1 element with class "title", so it
943+can be suppressed or reformatted with CSS.
944+If a title prefix is specified with \f[C]-T\f[] and no title block
945+appears in the document, the title prefix will be used by itself as the
946+HTML title.
947+.PP
948+The man page writer extracts a title, man page section number, and other
949+header and footer information from the title line.
950+The title is assumed to be the first word on the title line, which may
951+optionally end with a (single-digit) section number in parentheses.
952+(There should be no space between the title and the parentheses.)
953+ Anything after this is assumed to be additional footer and header text.
954+A single pipe character (\f[C]|\f[]) should be used to separate the
955+footer text from the header text.
956+Thus,
957+.IP
958+.nf
959+\f[C]
960+%\ PANDOC(1)
961+\f[]
962+.fi
963+.PP
964+will yield a man page with the title \f[C]PANDOC\f[] and section 1.
965+.IP
966+.nf
967+\f[C]
968+%\ PANDOC(1)\ Pandoc\ User\ Manuals
969+\f[]
970+.fi
971+.PP
972+will also have "Pandoc User Manuals" in the footer.
973+.IP
974+.nf
975+\f[C]
976+%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0
977+\f[]
978+.fi
979+.PP
980+will also have "Version 4.0" in the header.
981+.SH BACKSLASH ESCAPES
982+.PP
983+Except inside a code block or inline code, any punctuation or space
984+character preceded by a backslash will be treated literally, even if it
985+would normally indicate formatting.
986+Thus, for example, if one writes
987+.IP
988+.nf
989+\f[C]
990+*\\*hello\\**
991+\f[]
992+.fi
993+.PP
994+one will get
995+.IP
996+.nf
997+\f[C]
998+<em>*hello*</em>
999+\f[]
1000+.fi
1001+.PP
1002+instead of
1003+.IP
1004+.nf
1005+\f[C]
1006+<strong>hello</strong>
1007+\f[]
1008+.fi
1009+.PP
1010+This rule is easier to remember than standard markdown\[aq]s rule, which
1011+allows only the following characters to be backslash-escaped:
1012+.IP
1013+.nf
1014+\f[C]
1015+\\`*_{}[]()>#+-.!
1016+\f[]
1017+.fi
1018+.PP
1019+(However, if the \f[C]--strict\f[] option is supplied, the standard
1020+markdown rule will be used.)
1021+.PP
1022+A backslash-escaped space is parsed as a nonbreaking space.
1023+It will appear in TeX output as \f[C]~\f[] and in HTML and XML as
1024+\f[C]\\ \f[] or \f[C]\\ \f[].
1025+.PP
1026+A backslash-escaped newline (i.e.
1027+a backslash occurring at the end of a line) is parsed as a hard line
1028+break.
1029+It will appear in TeX output as \f[C]\\\\\f[] and in HTML as
1030+\f[C]<br\ />\f[].
1031+This is a nice alternative to markdown\[aq]s "invisible" way of
1032+indicating hard line breaks using two trailing spaces on a line.
1033+.PP
1034+Backslash escapes do not work in verbatim contexts.
1035+.SH SMART PUNCTUATION
1036+.PP
1037+If the \f[C]--smart\f[] option is specified, pandoc will produce
1038+typographically correct output, converting straight quotes to curly
1039+quotes, \f[C]---\f[] and \f[C]--\f[] to Em-dashes, and \f[C]...\f[] to
1040+ellipses.
1041+Nonbreaking spaces are inserted after certain abbreviations, such as
1042+"Mr."
1043+.PP
1044+Note: if your LaTeX template uses the \f[C]csquotes\f[] package, pandoc
1045+will detect automatically this and use \f[C]\\enquote{...}\f[] for
1046+quoted text.
1047+.SH INLINE FORMATTING
1048+.SS Emphasis
1049+.PP
1050+To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or
1051+\f[C]_\f[], like this:
1052+.IP
1053+.nf
1054+\f[C]
1055+This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this
1056+is\ *emphasized\ with\ asterisks*.
1057+\f[]
1058+.fi
1059+.PP
1060+Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:
1061+.IP
1062+.nf
1063+\f[C]
1064+This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.
1065+\f[]
1066+.fi
1067+.PP
1068+A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or
1069+backslash-escaped, will not trigger emphasis:
1070+.IP
1071+.nf
1072+\f[C]
1073+This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.
1074+\f[]
1075+.fi
1076+.PP
1077+Because \f[C]_\f[] is sometimes used inside words and identifiers,
1078+pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric
1079+characters as an emphasis marker.
1080+If you want to emphasize just part of a word, use \f[C]*\f[]:
1081+.IP
1082+.nf
1083+\f[C]
1084+feas*ible*,\ not\ feas*able*.
1085+\f[]
1086+.fi
1087+.SS Strikeout
1088+.PP
1089+\f[I]Pandoc extension\f[].
1090+.PP
1091+To strikeout a section of text with a horizontal line, begin and end it
1092+with \f[C]~~\f[].
1093+Thus, for example,
1094+.IP
1095+.nf
1096+\f[C]
1097+This\ ~~is\ deleted\ text.~~
1098+\f[]
1099+.fi
1100+.SS Superscripts and subscripts
1101+.PP
1102+\f[I]Pandoc extension\f[].
1103+.PP
1104+Superscripts may be written by surrounding the superscripted text by
1105+\f[C]^\f[] characters; subscripts may be written by surrounding the
1106+subscripted text by \f[C]~\f[] characters.
1107+Thus, for example,
1108+.IP
1109+.nf
1110+\f[C]
1111+H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.
1112+\f[]
1113+.fi
1114+.PP
1115+If the superscripted or subscripted text contains spaces, these spaces
1116+must be escaped with backslashes.
1117+(This is to prevent accidental superscripting and subscripting through
1118+the ordinary use of \f[C]~\f[] and \f[C]^\f[].)
1119+ Thus, if you want the letter P with \[aq]a cat\[aq] in subscripts, use
1120+\f[C]P~a\\\ cat~\f[], not \f[C]P~a\ cat~\f[].
1121+.SS Verbatim
1122+.PP
1123+To make a short span of text verbatim, put it inside backticks:
1124+.IP
1125+.nf
1126+\f[C]
1127+What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`?
1128+\f[]
1129+.fi
1130+.PP
1131+If the verbatim text includes a backtick, use double backticks:
1132+.IP
1133+.nf
1134+\f[C]
1135+Here\ is\ a\ literal\ backtick\ ``\ `\ ``.
1136+\f[]
1137+.fi
1138+.PP
1139+(The spaces after the opening backticks and before the closing backticks
1140+will be ignored.)
1141+.PP
1142+The general rule is that a verbatim span starts with a string of
1143+consecutive backticks (optionally followed by a space) and ends with a
1144+string of the same number of backticks (optionally preceded by a space).
1145+.PP
1146+Note that backslash-escapes (and other markdown constructs) do not work
1147+in verbatim contexts:
1148+.IP
1149+.nf
1150+\f[C]
1151+This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`.
1152+\f[]
1153+.fi
1154+.SH MATH
1155+.PP
1156+\f[I]Pandoc extension\f[].
1157+.PP
1158+Anything between two \f[C]$\f[] characters will be treated as TeX math.
1159+The opening \f[C]$\f[] must have a character immediately to its right,
1160+while the closing \f[C]$\f[] must have a character immediately to its
1161+left.
1162+Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math.
1163+If for some reason you need to enclose text in literal \f[C]$\f[]
1164+characters, backslash-escape them and they won\[aq]t be treated as math
1165+delimiters.
1166+.PP
1167+TeX math will be printed in all output formats.
1168+How it is rendered depends on the output format:
1169+.TP
1170+.B Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
1171+It will appear verbatim between \f[C]$\f[] characters.
1172+.RS
1173+.RE
1174+.TP
1175+.B reStructuredText
1176+It will be rendered using an interpreted text role \f[C]:math:\f[], as
1177+described here.
1178+.RS
1179+.RE
1180+.TP
1181+.B Texinfo
1182+It will be rendered inside a \f[C]\@math\f[] command.
1183+.RS
1184+.RE
1185+.TP
1186+.B groff man
1187+It will be rendered verbatim without \f[C]$\f[]\[aq]s.
1188+.RS
1189+.RE
1190+.TP
1191+.B MediaWiki
1192+It will be rendered inside \f[C]<math>\f[] tags.
1193+.RS
1194+.RE
1195+.TP
1196+.B Textile
1197+It will be rendered inside \f[C]<span\ class="math">\f[] tags.
1198+.RS
1199+.RE
1200+.TP
1201+.B RTF, Docbook, OpenDocument, ODT
1202+It will be rendered, if possible, using unicode characters, and will
1203+otherwise appear verbatim.
1204+.RS
1205+.RE
1206+.TP
1207+.B HTML, Slidy, DZSlides, S5, EPUB
1208+The way math is rendered in HTML will depend on the command-line options
1209+selected:
1210+.RS
1211+.IP "1." 3
1212+The default is to render TeX math as far as possible using unicode
1213+characters, as with RTF, Docbook, and OpenDocument output.
1214+Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so
1215+that they may be styled differently from the surrounding text if needed.
1216+.IP "2." 3
1217+If the \f[C]--latexmathml\f[] option is used, TeX math will be displayed
1218+between $ or $$ characters and put in \f[C]<span>\f[] tags with class
1219+\f[C]LaTeX\f[].
1220+The LaTeXMathML script will be used to render it as formulas.
1221+(This trick does not work in all browsers, but it works in Firefox.
1222+In browsers that do not support LaTeXMathML, TeX math will appear
1223+verbatim between $ characters.)
1224+.IP "3." 3
1225+If the \f[C]--jsmath\f[] option is used, TeX math will be put inside
1226+\f[C]<span>\f[] tags (for inline math) or \f[C]<div>\f[] tags (for
1227+display math) with class \f[C]math\f[].
1228+The jsMath script will be used to render it.
1229+.IP "4." 3
1230+If the \f[C]--mimetex\f[] option is used, the mimeTeX CGI script will be
1231+called to generate images for each TeX formula.
1232+This should work in all browsers.
1233+The \f[C]--mimetex\f[] option takes an optional URL as argument.
1234+If no URL is specified, it will be assumed that the mimeTeX CGI script
1235+is at \f[C]/cgi-bin/mimetex.cgi\f[].
1236+.IP "5." 3
1237+If the \f[C]--gladtex\f[] option is used, TeX formulas will be enclosed
1238+in \f[C]<eq>\f[] tags in the HTML output.
1239+The resulting \f[C]htex\f[] file may then be processed by gladTeX, which
1240+will produce image files for each formula and an \f[C]html\f[] file with
1241+links to these images.
1242+So, the procedure is:
1243+.RS 4
1244+.IP
1245+.nf
1246+\f[C]
1247+pandoc\ -s\ --gladtex\ myfile.txt\ -o\ myfile.htex
1248+gladtex\ -d\ myfile-images\ myfile.htex
1249+#\ produces\ myfile.html\ and\ images\ in\ myfile-images
1250+\f[]
1251+.fi
1252+.RE
1253+.IP "6." 3
1254+If the \f[C]--webtex\f[] option is used, TeX formulas will be converted
1255+to \f[C]<img>\f[] tags that link to an external script that converts
1256+formulas to images.
1257+The formula will be URL-encoded and concatenated with the URL provided.
1258+If no URL is specified, the Google Chart API will be used
1259+(\f[C]http://chart.apis.google.com/chart?cht=tx&chl=\f[]).
1260+.RE
1261+.SH RAW HTML
1262+.PP
1263+Markdown allows you to insert raw HTML anywhere in a document (except
1264+verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and \f[C]&\f[] are
1265+interpreted literally).
1266+.PP
1267+The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides,
1268+EPUB, Markdown, and Textile output, and suppressed in other formats.
1269+.PP
1270+\f[I]Pandoc extension\f[].
1271+.PP
1272+Standard markdown allows you to include HTML "blocks": blocks of HTML
1273+between balanced tags that are separated from the surrounding text with
1274+blank lines, and start and end at the left margin.
1275+Within these blocks, everything is interpreted as HTML, not markdown; so
1276+(for example), \f[C]*\f[] does not signify emphasis.
1277+.PP
1278+Pandoc behaves this way when \f[C]--strict\f[] is specified; but by
1279+default, pandoc interprets material between HTML block tags as markdown.
1280+Thus, for example, Pandoc will turn
1281+.IP
1282+.nf
1283+\f[C]
1284+<table>
1285+\ <tr>
1286+\ \ <td>*one*</td>
1287+\ \ <td>[a\ link](http://google.com)</td>
1288+\ </tr>
1289+</table>
1290+\f[]
1291+.fi
1292+.PP
1293+into
1294+.IP
1295+.nf
1296+\f[C]
1297+<table>
1298+\ <tr>
1299+\ \ <td><em>one</em></td>
1300+\ \ <td><a\ href="http://google.com">a\ link</a></td>
1301+\ </tr>
1302+</table>
1303+\f[]
1304+.fi
1305+.PP
1306+whereas \f[C]Markdown.pl\f[] will preserve it as is.
1307+.PP
1308+There is one exception to this rule: text between \f[C]<script>\f[] and
1309+\f[C]<style>\f[] tags is not interpreted as markdown.
1310+.PP
1311+This departure from standard markdown should make it easier to mix
1312+markdown with HTML block elements.
1313+For example, one can surround a block of markdown text with
1314+\f[C]<div>\f[] tags without preventing it from being interpreted as
1315+markdown.
1316+.SH RAW TEX
1317+.PP
1318+\f[I]Pandoc extension\f[].
1319+.PP
1320+In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
1321+included in a document.
1322+Inline TeX commands will be preserved and passed unchanged to the LaTeX
1323+and ConTeXt writers.
1324+Thus, for example, you can use LaTeX to include BibTeX citations:
1325+.IP
1326+.nf
1327+\f[C]
1328+This\ result\ was\ proved\ in\ \\cite{jones.1967}.
1329+\f[]
1330+.fi
1331+.PP
1332+Note that in LaTeX environments, like
1333+.IP
1334+.nf
1335+\f[C]
1336+\\begin{tabular}{|l|l|}\\hline
1337+Age\ &\ Frequency\ \\\\\ \\hline
1338+18--25\ \ &\ 15\ \\\\
1339+26--35\ \ &\ 33\ \\\\\
1340+36--45\ \ &\ 22\ \\\\\ \\hline
1341+\\end{tabular}
1342+\f[]
1343+.fi
1344+.PP
1345+the material between the begin and end tags will be interpreted as raw
1346+LaTeX, not as markdown.
1347+.PP
1348+Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
1349+and ConTeXt.
1350+.SS Macros
1351+.PP
1352+For output formats other than LaTeX, pandoc will parse LaTeX
1353+\f[C]\\newcommand\f[] and \f[C]\\renewcommand\f[] definitions and apply
1354+the resulting macros to all LaTeX math.
1355+So, for example, the following will work in all output formats, not just
1356+LaTeX:
1357+.IP
1358+.nf
1359+\f[C]
1360+\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle}
1361+
1362+$\\tuple{a,\ b,\ c}$
1363+\f[]
1364+.fi
1365+.PP
1366+In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be
1367+passed unchanged to the output.
1368+.SH LINKS
1369+.PP
1370+Markdown allows links to be specified in several ways.
1371+.SS Automatic links
1372+.PP
1373+If you enclose a URL or email address in pointy brackets, it will become
1374+a link:
1375+.IP
1376+.nf
1377+\f[C]
1378+<http://google.com>
1379+<sam\@green.eggs.ham>
1380+\f[]
1381+.fi
1382+.SS Inline links
1383+.PP
1384+An inline link consists of the link text in square brackets, followed by
1385+the URL in parentheses.
1386+(Optionally, the URL can be followed by a link title, in quotes.)
1387+.IP
1388+.nf
1389+\f[C]
1390+This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with
1391+a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!").
1392+\f[]
1393+.fi
1394+.PP
1395+There can be no space between the bracketed part and the parenthesized
1396+part.
1397+The link text can contain formatting (such as emphasis), but the title
1398+cannot.
1399+.SS Reference links
1400+.PP
1401+An \f[I]explicit\f[] reference link has two parts, the link itself and
1402+the link definition, which may occur elsewhere in the document (either
1403+before or after the link).
1404+.PP
1405+The link consists of link text in square brackets, followed by a label
1406+in square brackets.
1407+(There can be space between the two.)
1408+ The link definition must begin at the left margin or indented no more
1409+than three spaces.
1410+It consists of the bracketed label, followed by a colon and a space,
1411+followed by the URL, and optionally (after a space) a link title either
1412+in quotes or in parentheses.
1413+.PP
1414+Here are some examples:
1415+.IP
1416+.nf
1417+\f[C]
1418+[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional"
1419+[my\ label\ 2]:\ /foo
1420+[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation)
1421+[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq]
1422+\f[]
1423+.fi
1424+.PP
1425+The URL may optionally be surrounded by angle brackets:
1426+.IP
1427+.nf
1428+\f[C]
1429+[my\ label\ 5]:\ <http://foo.bar.baz>
1430+\f[]
1431+.fi
1432+.PP
1433+The title may go on the next line:
1434+.IP
1435+.nf
1436+\f[C]
1437+[my\ label\ 3]:\ http://fsf.org
1438+\ \ "The\ free\ software\ foundation"
1439+\f[]
1440+.fi
1441+.PP
1442+Note that link labels are not case sensitive.
1443+So, this will work:
1444+.IP
1445+.nf
1446+\f[C]
1447+Here\ is\ [my\ link][FOO]
1448+
1449+[Foo]:\ /bar/baz
1450+\f[]
1451+.fi
1452+.PP
1453+In an \f[I]implicit\f[] reference link, the second pair of brackets is
1454+empty, or omitted entirely:
1455+.IP
1456+.nf
1457+\f[C]
1458+See\ [my\ website][],\ or\ [my\ website].
1459+
1460+[my\ website]:\ http://foo.bar.baz
1461+\f[]
1462+.fi
1463+.SH IMAGES
1464+.PP
1465+A link immediately preceded by a \f[C]!\f[] will be treated as an image.
1466+The link text will be used as the image\[aq]s alt text:
1467+.IP
1468+.nf
1469+\f[C]
1470+
1471+
1472+![movie\ reel]
1473+
1474+[movie\ reel]:\ movie.gif
1475+\f[]
1476+.fi
1477+.SS Pictures with captions
1478+.PP
1479+\f[I]Pandoc extension\f[].
1480+.PP
1481+An image occurring by itself in a paragraph will be rendered as a figure
1482+with a caption.[4] (In LaTeX, a figure environment will be used; in
1483+HTML, the image will be placed in a \f[C]div\f[] with class
1484+\f[C]figure\f[], together with a caption in a \f[C]p\f[] with class
1485+\f[C]caption\f[].)
1486+ The image\[aq]s alt text will be used as the caption.
1487+.IP
1488+.nf
1489+\f[C]
1490+
1491+\f[]
1492+.fi
1493+.PP
1494+If you just want a regular inline image, just make sure it is not the
1495+only thing in the paragraph.
1496+One way to do this is to insert a nonbreaking space after the image:
1497+.IP
1498+.nf
1499+\f[C]
1500+![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\
1501+\f[]
1502+.fi
1503+.SH FOOTNOTES
1504+.PP
1505+\f[I]Pandoc extension\f[].
1506+.PP
1507+Pandoc\[aq]s markdown allows footnotes, using the following syntax:
1508+.IP
1509+.nf
1510+\f[C]
1511+Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote]
1512+
1513+[^1]:\ Here\ is\ the\ footnote.
1514+
1515+[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks.
1516+
1517+\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they\
1518+belong\ to\ the\ previous\ footnote.
1519+
1520+\ \ \ \ \ \ \ \ {\ some.code\ }
1521+
1522+\ \ \ \ The\ whole\ paragraph\ can\ be\ indented,\ or\ just\ the\ first
1523+\ \ \ \ line.\ \ In\ this\ way,\ multi-paragraph\ footnotes\ work\ like
1524+\ \ \ \ multi-paragraph\ list\ items.
1525+
1526+This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it
1527+isn\[aq]t\ indented.
1528+\f[]
1529+.fi
1530+.PP
1531+The identifiers in footnote references may not contain spaces, tabs, or
1532+newlines.
1533+These identifiers are used only to correlate the footnote reference with
1534+the note itself; in the output, footnotes will be numbered sequentially.
1535+.PP
1536+The footnotes themselves need not be placed at the end of the document.
1537+They may appear anywhere except inside other block elements (lists,
1538+block quotes, tables, etc.)
1539+\&.
1540+.PP
1541+Inline footnotes are also allowed (though, unlike regular notes, they
1542+cannot contain multiple paragraphs).
1543+The syntax is as follows:
1544+.IP
1545+.nf
1546+\f[C]
1547+Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since
1548+you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the
1549+note.]
1550+\f[]
1551+.fi
1552+.PP
1553+Inline and regular footnotes may be mixed freely.
1554+.SH CITATIONS
1555+.PP
1556+\f[I]Pandoc extension\f[].
1557+.PP
1558+Pandoc can automatically generate citations and a bibliography in a
1559+number of styles (using Andrea Rossato\[aq]s \f[C]hs-citeproc\f[]).
1560+In order to use this feature, you will need a bibliographic database in
1561+one of the following formats:
1562+.PP
1563+.TS
1564+tab(@);
1565+l l.
1566+T{
1567+Format
1568+T}@T{
1569+File extension
1570+T}
1571+_
1572+T{
1573+MODS
1574+T}@T{
1575+\&.mods
1576+T}
1577+T{
1578+BibTeX/BibLaTeX
1579+T}@T{
1580+\&.bib
1581+T}
1582+T{
1583+RIS
1584+T}@T{
1585+\&.ris
1586+T}
1587+T{
1588+EndNote
1589+T}@T{
1590+\&.enl
1591+T}
1592+T{
1593+EndNote XML
1594+T}@T{
1595+\&.xml
1596+T}
1597+T{
1598+ISI
1599+T}@T{
1600+\&.wos
1601+T}
1602+T{
1603+MEDLINE
1604+T}@T{
1605+\&.medline
1606+T}
1607+T{
1608+Copac
1609+T}@T{
1610+\&.copac
1611+T}
1612+T{
1613+JSON citeproc
1614+T}@T{
1615+\&.json
1616+T}
1617+.TE
1618+.PP
1619+You will need to specify the bibliography file using the
1620+\f[C]--bibliography\f[] command-line option (which may be repeated if
1621+you have several bibliographies).
1622+.PP
1623+By default, pandoc will use a Chicago author-date format for citations
1624+and references.
1625+To use another style, you will need to use the \f[C]--csl\f[] option to
1626+specify a CSL 1.0 style file.
1627+A primer on creating and modifying CSL styles can be found at
1628+\f[C]http://citationstyles.org/downloads/primer.html\f[].
1629+A repository of CSL styles can be found at
1630+\f[C]https://github.com/citation-style-language/styles\f[].
1631+See also \f[C]http://zotero.org/styles\f[] for easy browsing.
1632+.PP
1633+Citations go inside square brackets and are separated by semicolons.
1634+Each citation must have a key, composed of \[aq]\@\[aq] + the citation
1635+identifier from the database, and may optionally have a prefix, a
1636+locator, and a suffix.
1637+Here are some examples:
1638+.IP
1639+.nf
1640+\f[C]
1641+Blah\ blah\ [see\ \@doe99,\ pp.\ 33-35;\ also\ \@smith04,\ ch.\ 1].
1642+
1643+Blah\ blah\ [\@doe99,\ pp.\ 33-35,\ 38-39\ and\ *passim*].
1644+
1645+Blah\ blah\ [\@smith04;\ \@doe99].
1646+\f[]
1647+.fi
1648+.PP
1649+A minus sign (\f[C]-\f[]) before the \f[C]\@\f[] will suppress mention
1650+of the author in the citation.
1651+This can be useful when the author is already mentioned in the text:
1652+.IP
1653+.nf
1654+\f[C]
1655+Smith\ says\ blah\ [-\@smith04].
1656+\f[]
1657+.fi
1658+.PP
1659+You can also write an in-text citation, as follows:
1660+.IP
1661+.nf
1662+\f[C]
1663+\@smith04\ says\ blah.
1664+
1665+\@smith04\ [p.\ 33]\ says\ blah.
1666+\f[]
1667+.fi
1668+.PP
1669+If the style calls for a list of works cited, it will be placed at the
1670+end of the document.
1671+Normally, you will want to end your document with an appropriate header:
1672+.IP
1673+.nf
1674+\f[C]
1675+last\ paragraph...
1676+
1677+#\ References
1678+\f[]
1679+.fi
1680+.PP
1681+The bibliography will be inserted after this header.
1682+.SH NOTES
1683+.SS [1]
1684+.PP
1685+The point of this rule is to ensure that normal paragraphs starting with
1686+people\[aq]s initials, like
1687+.IP
1688+.nf
1689+\f[C]
1690+B.\ Russell\ was\ an\ English\ philosopher.
1691+\f[]
1692+.fi
1693+.PP
1694+do not get treated as list items.
1695+.PP
1696+This rule will not prevent
1697+.IP
1698+.nf
1699+\f[C]
1700+(C)\ 2007\ Joe\ Smith
1701+\f[]
1702+.fi
1703+.PP
1704+from being interpreted as a list item.
1705+In this case, a backslash escape can be used:
1706+.IP
1707+.nf
1708+\f[C]
1709+(C\\)\ 2007\ Joe\ Smith
1710+\f[]
1711+.fi
1712+.SS [2]
1713+.PP
1714+I have also been influenced by the suggestions of David Wheeler.
1715+.SS [3]
1716+.PP
1717+This scheme is due to Michel Fortin, who proposed it on the Markdown
1718+discussion list.
1719+.SS [4]
1720+.PP
1721+This feature is not yet implemented for RTF, OpenDocument, or ODT.
1722+In those formats, you\[aq]ll just get an image in a paragraph by itself,
1723+with no caption.
1724+.SH SEE ALSO
1725+.PP
1726+\f[C]pandoc\f[] (1).