diff options
authorJohn MacFarlane <>2018-03-02 20:23:53 -0800
committerJohn MacFarlane <>2018-03-02 20:23:53 -0800
commit5e6879dbf98eb5528c7f417b349118aadca40d71 (patch)
parent4d0eb272859767485db22d33e69c73a54cc7865e (diff)
Update man page and date on MANUAL.
2 files changed, 144 insertions, 11 deletions
diff --git a/MANUAL.txt b/MANUAL.txt
index cf95d8f6c..168f1784e 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -1,6 +1,6 @@
% Pandoc User's Guide
% John MacFarlane
-% January 18, 2018
+% March 2, 2018
diff --git a/man/pandoc.1 b/man/pandoc.1
index ee33b09ba..7cac72ebd 100644
--- a/man/pandoc.1
+++ b/man/pandoc.1
@@ -1,5 +1,5 @@
-.TH PANDOC 1 "January 18, 2018" "pandoc 2.1.1"
+.TH PANDOC 1 "March 2, 2018" "pandoc 2.1.2"
pandoc - general markup converter
@@ -175,7 +175,8 @@ When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
If \f[C]wkhtmltopdf\f[] is used, then the variables
\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
-\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output.
+\f[C]margin\-bottom\f[], \f[C]footer\-html\f[], \f[C]header\-html\f[]
+and \f[C]papersize\f[] will affect the output.
To debug the PDF creation, it can be useful to look at the intermediate
representation: instead of \f[C]\-o\ test.pdf\f[], use for example
@@ -821,6 +822,7 @@ line, or when resources used in a document must be downloaded).
Produce a standalone HTML file with no external dependencies, using
\f[C]data:\f[] URIs to incorporate the contents of linked scripts,
stylesheets, images, and videos.
+Implies \f[C]\-\-standalone\f[].
The resulting file should be "self\-contained," in the sense that it
needs no external files and no net access to be displayed properly by a
@@ -1044,6 +1046,34 @@ default \f[C]reference.odt\f[]:
Then open \f[C]custom\-reference.odt\f[] in LibreOffice, modify the
styles as you wish, and save the file.
+.B PowerPoint
+Any template included with a recent install of Microsoft PowerPoint
+(either with \f[C]\&.pptx\f[] or \f[C]\&.potx\f[] extension) should
+work, as will most templates derived from these.
+The specific requirement is that the template should contain the
+following four layouts as its first four layouts:
+.IP "1." 3
+Title Slide
+.IP "2." 3
+Title and Content
+.IP "3." 3
+Section Header
+.IP "4." 3
+Two Content
+All templates included with a recent version of MS PowerPoint will fit
+these criteria.
+(You can click on \f[C]Layout\f[] under the \f[C]Home\f[] menu to
+You can also modify the default \f[C]reference.pptx\f[]: first run
+\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.pptx\ >\ custom\-reference.pptx\f[],
+and then modify \f[C]custom\-reference.pptx\f[] in MS PowerPoint (pandoc
+will use the first four layout slides, as mentioned above).
.B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[]
@@ -2341,6 +2371,18 @@ This extension can be enabled/disabled for the following formats:
+.SS Extension: \f[C]styles\f[]
+Read all docx styles as divs (for paragraph styles) and spans (for
+character styles) regardless of whether pandoc understands the meaning
+of these styles.
+This can be used with docx custom styles.
+Disabled by default.
+.B input formats
.SS Extension: \f[C]amuse\f[]
In the \f[C]muse\f[] input format, this enables Text::Amuse extensions
@@ -2741,7 +2783,7 @@ Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and
with value \f[C]100\f[].
Some output formats can use this information to do syntax highlighting.
Currently, the only output formats that uses this information are HTML,
-LaTeX, Docx, and Ms.
+LaTeX, Docx, Ms, and PowerPoint.
If highlighting is supported for your output format and language, then
the code block above will appear highlighted, with numbered lines.
(To see which languages are supported, type
@@ -5204,9 +5246,42 @@ reveal.js.
By default, these writers produce lists that display "all at once." If
you want your lists to display incrementally (one item at a time), use
the \f[C]\-i\f[] option.
-If you want a particular list to depart from the default (that is, to
+If you want a particular list to depart from the default, put it in a
+\f[C]div\f[] block with class \f[C]incremental\f[] or
+So, for example, using the \f[C]fenced\ div\f[] syntax, the following
+would be incremental regardless of the document default:
+:::\ incremental
+\-\ Eat\ spaghetti
+\-\ Drink\ wine
+:::\ nonincremental
+\-\ Eat\ spaghetti
+\-\ Drink\ wine
+While using \f[C]incremental\f[] and \f[C]nonincremental\f[] divs are
+the recommended method of setting incremental lists on a per\-case
+basis, an older method is also supported: putting lists inside a
+blockquote will depart from the document default (that is, it will
display incrementally without the \f[C]\-i\f[] option and all at once
-with the \f[C]\-i\f[] option), put it in a block quote:
+with the \f[C]\-i\f[] option):
@@ -5215,7 +5290,7 @@ with the \f[C]\-i\f[] option), put it in a block quote:
-In this way incremental and nonincremental lists can be mixed in a
+Both methods allow incremental and nonincremental lists to be mixed in a
single document.
.SS Inserting pauses
@@ -5286,7 +5361,7 @@ This is recommended especially for bibliographies:
.SS Speaker notes
-reveal.js has good support for speaker notes.
+Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
You can add notes to your Markdown document thus:
@@ -5302,8 +5377,11 @@ This\ is\ my\ note.
-To show the notes window, press \f[C]s\f[] while viewing the
+To show the notes window in reveal.js, press \f[C]s\f[] while viewing
+the presentation.
+Speaker notes in PowerPoint will be available, as usual, in handouts and
+presenter view.
Notes are not yet supported for other slide formats, but the notes will
not appear on the slides themselves.
.SS Columns
@@ -5532,7 +5610,62 @@ To see a list of highlight styles, type
\f[C]pandoc\ \-\-list\-highlight\-styles\f[].
To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option.
+.SS Input
+The docx reader, by default, only reads those styles that it can convert
+into pandoc elements, either by direct conversion or interpreting the
+derivation of the input document\[aq]s styles.
+By enabling the \f[C]styles\f[] extension in the docx reader
+(\f[C]\-f\ docx+styles\f[]), you can produce output that maintains the
+styles of the input document, using the \f[C]custom\-style\f[] class.
+Paragraph styles are interpreted as divs, while character styles are
+interpreted as spans.
+For example, using the \f[C]custom\-style\-reference.docx\f[] file in
+the test directory, we have the following different outputs:
+Without the \f[C]+styles\f[] extension:
+$\ pandoc\ test/docx/custom\-style\-reference.docx\ \-f\ docx\ \-t\ markdown
+This\ is\ some\ text.
+This\ is\ text\ with\ an\ *emphasized*\ text\ style.\ And\ this\ is\ text\ with\ a
+**strengthened**\ text\ style.
+>\ Here\ is\ a\ styled\ paragraph\ that\ inherits\ from\ Block\ Text.
+And with the extension:
+$\ pandoc\ test/docx/custom\-style\-reference.docx\ \-f\ docx+styles\ \-t\ markdown
+:::\ {custom\-style="FirstParagraph"}
+This\ is\ some\ text.
+:::\ {custom\-style="BodyText"}
+This\ is\ text\ with\ an\ [emphasized]{custom\-style="Emphatic"}\ text\ style.
+And\ this\ is\ text\ with\ a\ [strengthened]{custom\-style="Strengthened"}
+text\ style.
+:::\ {custom\-style="MyBlockStyle"}
+>\ Here\ is\ a\ styled\ paragraph\ that\ inherits\ from\ Block\ Text.
+With these custom styles, you can use your input document as a
+reference\-doc while creating docx output (see below), and maintain the
+same styles in your input and output files.
+.SS Output
By default, pandoc\[aq]s docx output applies a predefined set of styles
for blocks such as paragraphs and block quotes, and uses largely default