@@ -1,6 +1,6 @@
11% Pandoc User's Guide
22% John MacFarlane
3−% January 7, 2018
3+% January 18, 2018
44
55Synopsis
66========
@@ -349,15 +349,15 @@ General options
349349 If this option is not specified, the default user data directory
350350 will be used. This is, in UNIX:
351351
352− $HOME/.pandoc
352+ $HOME/.pandoc
353353
354354 in Windows XP:
355355
356− C:\Documents And Settings\USERNAME\Application Data\pandoc
356+ C:\Documents And Settings\USERNAME\Application Data\pandoc
357357
358358 and in Windows Vista or later:
359359
360− C:\Users\USERNAME\AppData\Roaming\pandoc
360+ C:\Users\USERNAME\AppData\Roaming\pandoc
361361
362362 You can find the default user data directory on your system by
363363 looking at the output of `pandoc --version`.
@@ -370,7 +370,7 @@ General options
370370: Generate a bash completion script. To enable bash completion
371371 with pandoc, add this to your `.bashrc`:
372372
373− eval "$(pandoc --bash-completion)"
373+ eval "$(pandoc --bash-completion)"
374374
375375`--verbose`
376376
@@ -468,11 +468,11 @@ Reader options
468468 JSON input and output. The name of the output format will be
469469 passed to the filter as the first argument. Hence,
470470
471− pandoc --filter ./caps.py -t latex
471+ pandoc --filter ./caps.py -t latex
472472
473473 is equivalent to
474474
475− pandoc -t json | ./caps.py latex | pandoc -f json -t latex
475+ pandoc -t json | ./caps.py latex | pandoc -f json -t latex
476476
477477 The latter form may be useful for debugging filters.
478478
@@ -511,15 +511,15 @@ Reader options
511511
512512 The following is an example lua script for macro-expansion:
513513
514− function expand_hello_world(inline)
515− if inline.c == '{{helloworld}}' then
516− return pandoc.Emph{ pandoc.Str "Hello, World" }
517− else
518− return inline
519− end
520− end
514+ function expand_hello_world(inline)
515+ if inline.c == '{{helloworld}}' then
516+ return pandoc.Emph{ pandoc.Str "Hello, World" }
517+ else
518+ return inline
519+ end
520+ end
521521
522− return {{Str = expand_hello_world}}
522+ return {{Str = expand_hello_world}}
523523
524524
525525`-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*]
@@ -919,48 +919,48 @@ Options affecting specific writers
919919 Docx
920920
921921 : For best results, the reference docx should be a modified
922− version of a docx file produced using pandoc. The contents
923− of the reference docx are ignored, but its stylesheets and
924− document properties (including margins, page size, header,
925− and footer) are used in the new docx. If no reference docx
926− is specified on the command line, pandoc will look for a
927− file `reference.docx` in the user data directory (see
928− `--data-dir`). If this is not found either, sensible
929− defaults will be used.
930−
931− To produce a custom `reference.docx`, first get a copy of
932− the default `reference.docx`: `pandoc
933− --print-default-data-file reference.docx >
934− custom-reference.docx`. Then open `custom-reference.docx`
935− in Word, modify the styles as you wish, and save the file.
936− For best results, do not make changes to this file other
937− than modifying the styles used by pandoc: [paragraph]
938− Normal, Body Text, First Paragraph, Compact, Title,
939− Subtitle, Author, Date, Abstract, Bibliography, Heading 1,
940− Heading 2, Heading 3, Heading 4, Heading 5, Heading 6,
941− Heading 7, Heading 8, Heading 9, Block Text, Footnote Text,
942− Definition Term, Definition, Caption, Table Caption,
943− Image Caption, Figure, Captioned Figure, TOC Heading;
944− [character] Default Paragraph Font, Body Text Char,
945− Verbatim Char, Footnote Reference, Hyperlink; [table]
946− Table.
922+ version of a docx file produced using pandoc. The contents
923+ of the reference docx are ignored, but its stylesheets and
924+ document properties (including margins, page size, header,
925+ and footer) are used in the new docx. If no reference docx
926+ is specified on the command line, pandoc will look for a
927+ file `reference.docx` in the user data directory (see
928+ `--data-dir`). If this is not found either, sensible
929+ defaults will be used.
930+
931+ To produce a custom `reference.docx`, first get a copy of
932+ the default `reference.docx`: `pandoc
933+ --print-default-data-file reference.docx >
934+ custom-reference.docx`. Then open `custom-reference.docx`
935+ in Word, modify the styles as you wish, and save the file.
936+ For best results, do not make changes to this file other
937+ than modifying the styles used by pandoc: [paragraph]
938+ Normal, Body Text, First Paragraph, Compact, Title,
939+ Subtitle, Author, Date, Abstract, Bibliography, Heading 1,
940+ Heading 2, Heading 3, Heading 4, Heading 5, Heading 6,
941+ Heading 7, Heading 8, Heading 9, Block Text, Footnote Text,
942+ Definition Term, Definition, Caption, Table Caption,
943+ Image Caption, Figure, Captioned Figure, TOC Heading;
944+ [character] Default Paragraph Font, Body Text Char,
945+ Verbatim Char, Footnote Reference, Hyperlink; [table]
946+ Table.
947947
948948 ODT
949949
950950 : For best results, the reference ODT should be a modified
951− version of an ODT produced using pandoc. The contents of
952− the reference ODT are ignored, but its stylesheets are used
953− in the new ODT. If no reference ODT is specified on the
954− command line, pandoc will look for a file `reference.odt` in
955− the user data directory (see `--data-dir`). If this is not
956− found either, sensible defaults will be used.
957−
958− To produce a custom `reference.odt`, first get a copy of
959− the default `reference.odt`: `pandoc
960− --print-default-data-file reference.odt >
961− custom-reference.odt`. Then open `custom-reference.odt` in
962− LibreOffice, modify the styles as you wish, and save the
963− file.
951+ version of an ODT produced using pandoc. The contents of
952+ the reference ODT are ignored, but its stylesheets are used
953+ in the new ODT. If no reference ODT is specified on the
954+ command line, pandoc will look for a file `reference.odt` in
955+ the user data directory (see `--data-dir`). If this is not
956+ found either, sensible defaults will be used.
957+
958+ To produce a custom `reference.odt`, first get a copy of
959+ the default `reference.odt`: `pandoc
960+ --print-default-data-file reference.odt >
961+ custom-reference.odt`. Then open `custom-reference.odt` in
962+ LibreOffice, modify the styles as you wish, and save the
963+ file.
964964
965965`--epub-cover-image=`*FILE*
966966
@@ -975,8 +975,8 @@ Options affecting specific writers
975975 The file should contain a series of [Dublin Core elements].
976976 For example:
977977
978− <dc:rights>Creative Commons</dc:rights>
979− <dc:language>es-AR</dc:language>
978+ <dc:rights>Creative Commons</dc:rights>
979+ <dc:language>es-AR</dc:language>
980980
981981 By default, pandoc will include the following metadata elements:
982982 `<dc:title>` (from the document title), `<dc:creator>` (from the
@@ -1000,31 +1000,31 @@ Options affecting specific writers
10001000 embedded fonts, you will need to add declarations like the following
10011001 to your CSS (see `--css`):
10021002
1003− @font-face {
1004− font-family: DejaVuSans;
1005− font-style: normal;
1006− font-weight: normal;
1007− src:url("DejaVuSans-Regular.ttf");
1008− }
1009− @font-face {
1010− font-family: DejaVuSans;
1011− font-style: normal;
1012− font-weight: bold;
1013− src:url("DejaVuSans-Bold.ttf");
1014− }
1015− @font-face {
1016− font-family: DejaVuSans;
1017− font-style: italic;
1018− font-weight: normal;
1019− src:url("DejaVuSans-Oblique.ttf");
1020− }
1021− @font-face {
1022− font-family: DejaVuSans;
1023− font-style: italic;
1024− font-weight: bold;
1025− src:url("DejaVuSans-BoldOblique.ttf");
1026− }
1027− body { font-family: "DejaVuSans"; }
1003+ @font-face {
1004+ font-family: DejaVuSans;
1005+ font-style: normal;
1006+ font-weight: normal;
1007+ src:url("DejaVuSans-Regular.ttf");
1008+ }
1009+ @font-face {
1010+ font-family: DejaVuSans;
1011+ font-style: normal;
1012+ font-weight: bold;
1013+ src:url("DejaVuSans-Bold.ttf");
1014+ }
1015+ @font-face {
1016+ font-family: DejaVuSans;
1017+ font-style: italic;
1018+ font-weight: normal;
1019+ src:url("DejaVuSans-Oblique.ttf");
1020+ }
1021+ @font-face {
1022+ font-family: DejaVuSans;
1023+ font-style: italic;
1024+ font-weight: bold;
1025+ src:url("DejaVuSans-BoldOblique.ttf");
1026+ }
1027+ body { font-family: "DejaVuSans"; }
10281028
10291029`--epub-chapter-level=`*NUMBER*
10301030
@@ -1177,9 +1177,9 @@ of the following options.
11771177 formulas and an HTML file with links to these images.
11781178 So, the procedure is:
11791179
1180− pandoc -s --gladtex input.md -o myfile.htex
1181− gladtex -d myfile-images myfile.htex
1182− # produces myfile.html and images in myfile-images
1180+ pandoc -s --gladtex input.md -o myfile.htex
1181+ gladtex -d myfile-images myfile.htex
1182+ # produces myfile.html and images in myfile-images
11831183
11841184`--mimetex`[`=`*URL*]
11851185
@@ -1216,11 +1216,11 @@ Options for wrapper scripts
12161216: Ignore command-line arguments (for use in wrapper scripts).
12171217 Regular pandoc options are not ignored. Thus, for example,
12181218
1219− pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1219+ pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
12201220
12211221 is equivalent to
12221222
1223− pandoc -o foo.html -s
1223+ pandoc -o foo.html -s
12241224
12251225Templates
12261226=========
@@ -1266,13 +1266,13 @@ as the following:
12661266 if input is from stdin. You can use the following snippet in your template
12671267 to distinguish them:
12681268
1269− $if(sourcefile)$
1270− $for(sourcefile)$
1271− $sourcefile$
1272− $endfor$
1273− $else$
1274− (stdin)
1275− $endif$
1269+ $if(sourcefile)$
1270+ $for(sourcefile)$
1271+ $sourcefile$
1272+ $endfor$
1273+ $else$
1274+ (stdin)
1275+ $endif$
12761276
12771277 Similarly, `outputfile` can be `-` if output goes to the terminal.
12781278
@@ -1282,11 +1282,11 @@ as the following:
12821282 through a [pandoc title block][Extension: `pandoc_title_block`],
12831283 which allows for multiple authors, or through a YAML metadata block:
12841284
1285− ---
1286− author:
1287− - Aristotle
1288− - Peter Abelard
1289− ...
1285+ ---
1286+ author:
1287+ - Aristotle
1288+ - Peter Abelard
1289+ ...
12901290
12911291`subtitle`
12921292: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word docx;
@@ -1334,11 +1334,11 @@ as the following:
13341334[^subtitle]: To make `subtitle` work with other LaTeX
13351335 document classes, you can add the following to `header-includes`:
13361336
1337− \providecommand{\subtitle}[1]{%
1338− \usepackage{titling}
1339− \posttitle{%
1340− \par\large#1\end{center}}
1341− }
1337+ \providecommand{\subtitle}[1]{%
1338+ \usepackage{titling}
1339+ \posttitle{%
1340+ \par\large#1\end{center}}
1341+ }
13421342
13431343Language variables
13441344------------------
@@ -2208,9 +2208,9 @@ A block of text indented four spaces (or one tab) is treated as verbatim
22082208text: that is, special characters do not trigger special formatting,
22092209and all spaces and line breaks are preserved. For example,
22102210
2211− if (a > 3) {
2212− moveShip(5 * gravity, DOWN);
2213− }
2211+ if (a > 3) {
2212+ moveShip(5 * gravity, DOWN);
2213+ }
22142214
22152215The initial (four space or one tab) indentation is not considered part
22162216of the verbatim text, and is removed in the output.
@@ -2259,7 +2259,7 @@ this syntax:
22592259 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
22602260 qsort [] = []
22612261 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2262− qsort (filter (>= x) xs)
2262+ qsort (filter (>= x) xs)
22632263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22642264
22652265Here `mycode` is an identifier, `haskell` and `numberLines` are classes, and
@@ -2383,12 +2383,12 @@ the list marker.
23832383
23842384 * First paragraph.
23852385
2386− Continued.
2386+ Continued.
23872387
23882388 * Second paragraph. With a code block, which must be indented
2389− eight spaces:
2389+ eight spaces:
23902390
2391− { code }
2391+ { code }
23922392
23932393Exception: if the list marker is followed by an indented code
23942394block, which must begin 5 spaces after the list marker, then
@@ -2406,8 +2406,8 @@ containing list item.
24062406
24072407 * fruits
24082408 + apples
2409− - macintosh
2410− - red delicious
2409+ - macintosh
2410+ - red delicious
24112411 + pears
24122412 + peaches
24132413 * vegetables
@@ -2424,7 +2424,7 @@ other blocks in a list item, the first line of each must be indented.
24242424 + Another one; this looks
24252425 bad but is legal.
24262426
2427− Second paragraph of second
2427+ Second paragraph of second
24282428 list item.
24292429
24302430### Ordered lists ###
@@ -2458,18 +2458,18 @@ capital letter with a period, by at least two spaces.[^2]
24582458[^2]: The point of this rule is to ensure that normal paragraphs
24592459 starting with people's initials, like
24602460
2461− B. Russell was an English philosopher.
2461+ B. Russell was an English philosopher.
24622462
24632463 do not get treated as list items.
24642464
24652465 This rule will not prevent
24662466
2467− (C) 2007 Joe Smith
2467+ (C) 2007 Joe Smith
24682468
24692469 from being interpreted as a list item. In this case, a backslash
24702470 escape can be used:
24712471
2472− (C\) 2007 Joe Smith
2472+ (C\) 2007 Joe Smith
24732473
24742474The `fancy_lists` extension also allows '`#`' to be used as an
24752475ordered list marker in place of a numeral:
@@ -2488,9 +2488,9 @@ roman numerals:
24882488 9) Ninth
24892489 10) Tenth
24902490 11) Eleventh
2491− i. subone
2492− ii. subtwo
2493− iii. subthree
2491+ i. subone
2492+ ii. subtwo
2493+ iii. subthree
24942494
24952495Pandoc will start a new list each time a different type of list
24962496marker is used. So, the following will create three lists:
@@ -2522,9 +2522,9 @@ Pandoc supports definition lists, using the syntax of
25222522
25232523 : Definition 2
25242524
2525− { some code, part of Definition 2 }
2525+ { some code, part of Definition 2 }
25262526
2527− Third paragraph of definition 2.
2527+ Third paragraph of definition 2.
25282528
25292529Each term must fit on one line, which may optionally be followed by
25302530a blank line, and must be followed by one or more definitions.
@@ -2543,7 +2543,7 @@ at the beginning of a paragraph or other block element:
25432543 : Definition
25442544 with lazy continuation.
25452545
2546− Second paragraph of the definition.
2546+ Second paragraph of the definition.
25472547
25482548If you leave space before the definition (as in the example above),
25492549the text of the definition will be treated as a paragraph. In some
@@ -2606,9 +2606,9 @@ cases" involving lists. Consider this source:
26062606
26072607 + First
26082608 + Second:
2609− - Fee
2610− - Fie
2611− - Foe
2609+ - Fee
2610+ - Fie
2611+ - Foe
26122612
26132613 + Third
26142614
@@ -2631,7 +2631,7 @@ What if you want to put an indented code block after a list?
26312631 - item one
26322632 - item two
26332633
2634− { my code block }
2634+ { my code block }
26352635
26362636Trouble! Here pandoc (like other Markdown implementations) will treat
26372637`{ my code block }` as the second paragraph of item two, and not as
@@ -2646,7 +2646,7 @@ any format:
26462646
26472647 <!-- end of list -->
26482648
2649− { my code block }
2649+ { my code block }
26502650
26512651You can use the same trick if you want two consecutive lists instead
26522652of one big list:
@@ -2692,9 +2692,9 @@ Simple tables look like this:
26922692
26932693 Right Left Center Default
26942694 ------- ------ ---------- -------
2695− 12 12 12 12
2696− 123 123 123 123
2697− 1 1 1 1
2695+ 12 12 12 12
2696+ 123 123 123 123
2697+ 1 1 1 1
26982698
26992699 Table: Demonstration of simple table syntax.
27002700
@@ -2721,9 +2721,9 @@ The column headers may be omitted, provided a dashed line is used
27212721to end the table. For example:
27222722
27232723 ------- ------ ---------- -------
2724− 12 12 12 12
2725− 123 123 123 123
2726− 1 1 1 1
2724+ 12 12 12 12
2725+ 123 123 123 123
2726+ 1 1 1 1
27272727 ------- ------ ---------- -------
27282728
27292729When headers are omitted, column alignments are determined on the basis
@@ -2741,11 +2741,11 @@ not supported). Here is an example:
27412741 Header Aligned Aligned Aligned
27422742 ----------- ------- --------------- -------------------------
27432743 First row 12.0 Example of a row that
2744− spans multiple lines.
2744+ spans multiple lines.
27452745
27462746 Second row 5.0 Here's another one. Note
2747− the blank line between
2748− rows.
2747+ the blank line between
2748+ rows.
27492749 -------------------------------------------------------------
27502750
27512751 Table: Here's the caption. It, too, may span
@@ -2767,11 +2767,11 @@ Headers may be omitted in multiline tables as well as simple tables:
27672767
27682768 ----------- ------- --------------- -------------------------
27692769 First row 12.0 Example of a row that
2770− spans multiple lines.
2770+ spans multiple lines.
27712771
27722772 Second row 5.0 Here's another one. Note
2773− the blank line between
2774− rows.
2773+ the blank line between
2774+ rows.
27752775 ----------- ------- --------------- -------------------------
27762776
27772777 : Here's a multiline table without headers.
@@ -3664,14 +3664,14 @@ Pandoc's Markdown allows footnotes, using the following syntax:
36643664
36653665 [^longnote]: Here's one with multiple blocks.
36663666
3667− Subsequent paragraphs are indented to show that they
3667+ Subsequent paragraphs are indented to show that they
36683668 belong to the previous footnote.
36693669
3670− { some.code }
3670+ { some.code }
36713671
3672− The whole paragraph can be indented, or just the first
3673− line. In this way, multi-paragraph footnotes work like
3674− multi-paragraph list items.
3672+ The whole paragraph can be indented, or just the first
3673+ line. In this way, multi-paragraph footnotes work like
3674+ multi-paragraph list items.
36753675
36763676 This paragraph won't be part of the note, because it
36773677 isn't indented.
@@ -3771,16 +3771,16 @@ YAML-encoded references, for example:
37713771 id: WatsonCrick1953
37723772 author:
37733773 - family: Watson
3774− given: J. D.
3774+ given: J. D.
37753775 - family: Crick
3776− given: F. H. C.
3776+ given: F. H. C.
37773777 issued:
3778− date-parts:
3779− - - 1953
3780− - 4
3781− - 25
3778+ date-parts:
3779+ - - 1953
3780+ - 4
3781+ - 25
37823782 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3783− nucleic acid'
3783+ nucleic acid'
37843784 title-short: Molecular structure of nucleic acids
37853785 container-title: Nature
37863786 volume: 171
@@ -3981,7 +3981,7 @@ the document, for example:
39813981 Author: John Doe
39823982 Date: September 1, 2008
39833983 Comment: This is a sample mmd title block, with
3984− a field spanning multiple lines.
3984+ a field spanning multiple lines.
39853985
39863986See the MultiMarkdown documentation for details. If `pandoc_title_block` or
39873987`yaml_metadata_block` is enabled, it will take precedence over
@@ -4011,7 +4011,7 @@ and image references. This extension should not be confused with the
40114011 This is a reference ![image][ref] with multimarkdown attributes.
40124012
40134013 [ref]: http://path.to/image "Image title" width=20px height=30px
4014− id=myId class="myClass1 myClass2"
4014+ id=myId class="myClass1 myClass2"
40154015
40164016#### Extension: `mmd_header_identifiers` ####
40174017
@@ -4035,10 +4035,10 @@ in several respects:
40354035[^6]: To see why laziness is incompatible with relaxing the requirement
40364036 of a blank line between items, consider the following example:
40374037
4038− bar
4039− : definition
4040− foo
4041− : definition
4038+ bar
4039+ : definition
4040+ foo
4041+ : definition
40424042
40434043 Is this a single list item with two definitions of "bar," the first of
40444044 which is lazily wrapped, or two list items? To remove the ambiguity
@@ -4440,7 +4440,7 @@ with the `src` attribute. For example:
44404440
44414441 <audio controls="1">
44424442 <source src="http://example.com/music/toccata.mp3"
4443− data-external="1" type="audio/mpeg">
4443+ data-external="1" type="audio/mpeg">
44444444 </source>
44454445 </audio>
44464446