From b512573805650bc3609033ad9f65d7e5200e6969 Mon Sep 17 00:00:00 2001 From: Jesse Rosenthal Date: Mon, 15 Aug 2016 14:22:55 -0400 Subject: [PATCH] Add discussion of custom styles to MANUAL.txt. --- MANUAL.txt | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/MANUAL.txt b/MANUAL.txt index 2177cf926..38890c599 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -3827,6 +3827,54 @@ To disable highlighting, use the `--no-highlight` option. [highlighting-kate]: https://github.com/jgm/highlighting-kate +Custom Styles in Docx Output +============================ + +By default, pandoc's docx output applies a predefined set of styles for +blocks such as paragraphs and block quotes, and uses largely default +formatting (italics, bold) for inlines. This will work for most +purposes, especially alongside a `reference.docx` file. However, if you +need to apply your own styles to blocks, or match a preexisting set of +styles, pandoc allows you to define custom styles for blocks and text +using `div`s and `span`s, respecitively. + +If you define a `div` or `span` with the attribute `custom-style`, +pandoc will apply your specified style to the contained elements. So, +for example, + + Get out, he said. + +would produce a docx file with "Get out," styled with character +style `Emphatically`. Similarly, + + Dickinson starts the poem simply: + +
+ | A Bird came down the Walk--- + | He did not know I saw--- +
+ +Would style the two contained lines with the `Poetry` paragraph style. + +If the styles are not yet in your reference.docx, they will be defined +in the output file as inheriting from normal text. If they are already +defined, pandoc will not alter the definition. + +This feature allows for greatest customization in conjunction with +[pandoc filters]. If you want all paragraphs after block quotes to be +indented, you can write a filter to apply the styles necessary. If you +want all italics to be transformed to the `Emphasis` character style +(perhaps to change their color), you can write a filter which will +transform all italicized inlines + + Emph + +to + + Span ("", [], [("custom-style", "Emphasis")] + +[pandoc filters]: http://pandoc.org/scripting.html + Custom writers ==============