From 1a6fad9fbddd4cd7ebae236d6b4c11c0423bb0fd Mon Sep 17 00:00:00 2001 From: John MacFarlane <jgm@berkeley.edu> Date: Wed, 12 Jan 2022 15:12:53 -0800 Subject: [PATCH] Update manual date and man page. --- MANUAL.txt | 2 +- man/pandoc.1 | 71 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 52 insertions(+), 21 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index c71e1d86c..a9132a687 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: November 20, 2021 +date: January 12, 2022 --- # Synopsis diff --git a/man/pandoc.1 b/man/pandoc.1 index cbc100841..3821570ab 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,7 +1,7 @@ '\" t -.\" Automatically generated by Pandoc 2.16.1 +.\" Automatically generated by Pandoc 2.16.2 .\" -.TH "Pandoc User\[cq]s Guide" "" "November 20, 2021" "pandoc 2.16.2" "" +.TH "Pandoc User\[cq]s Guide" "" "January 12, 2022" "pandoc 2.17" "" .hy .SH NAME pandoc - general markup converter @@ -388,6 +388,8 @@ markup) .IP \[bu] 2 \f[C]markdown_strict\f[R] (original unextended Markdown) .IP \[bu] 2 +\f[C]markua\f[R] (Markua) +.IP \[bu] 2 \f[C]mediawiki\f[R] (MediaWiki markup) .IP \[bu] 2 \f[C]ms\f[R] (roff ms) @@ -823,7 +825,6 @@ With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping from the source document (that is, where there are nonsemantic newlines in the source, there will be nonsemantic newlines in the output as well). -Automatic wrapping does not currently work in HTML output. In \f[C]ipynb\f[R] output, this option affects wrapping of the contents of markdown cells. .TP @@ -2478,6 +2479,11 @@ documents document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx documents .TP +\f[B]\f[CB]abstract-title\f[B]\f[R] +title of abstract, currently used only in HTML and EPUB. +This will be set automatically to a localized value, depending on +\f[C]lang\f[R], but can be manually overridden. +.TP \f[B]\f[CB]keywords\f[B]\f[R] list of keywords to be included in HTML, PDF, ODT, pptx, docx and AsciiDoc metadata; repeat as for \f[C]author\f[R], above @@ -3540,6 +3546,17 @@ output format. .PP Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted in \f[C]org\f[R] input. +.SS Extension: \f[C]fancy_lists\f[R] +.PP +Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in +\f[C]org\f[R] input, mimicking the option +\f[C]org-list-allow-alphabetical\f[R] in Emacs. +As in Org Mode, enabling this extension allows lowercase and uppercase +alphabetical markers for ordered lists to be parsed in addition to +arabic ones. +Note that for Org, this does not include roman numerals or the +\f[C]#\f[R] placeholder that are enabled by the extension in +Pandoc\[cq]s Markdown. .SS Extension: \f[C]element_citations\f[R] .PP In the \f[C]jats\f[R] output formats, this causes reference items to be @@ -3556,7 +3573,7 @@ a performance penalty compared to extreme tables. .PP Pandoc understands an extended and slightly revised version of John Gruber\[cq]s Markdown syntax. -This document explains the syntax, noting differences from standard +This document explains the syntax, noting differences from original Markdown. Except where noted, these differences can be suppressed by using the \f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R]. @@ -3645,7 +3662,7 @@ As with setext-style headings, the heading text can contain formatting: .fi .SS Extension: \f[C]blank_before_header\f[R] .PP -Standard Markdown syntax does not require a blank line before a heading. +Original Markdown syntax does not require a blank line before a heading. 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 @@ -3849,7 +3866,7 @@ spaces after the \f[C]>\f[R]: .fi .SS Extension: \f[C]blank_before_blockquote\f[R] .PP -Standard Markdown syntax does not require a blank line before a block +Original 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). @@ -4162,7 +4179,7 @@ list item. 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 +In original 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: @@ -4186,7 +4203,7 @@ and this one: .fi .SS Extension: \f[C]fancy_lists\f[R] .PP -Unlike standard Markdown, pandoc allows ordered list items to be marked +Unlike original 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 @@ -4656,11 +4673,11 @@ orange|3.09 .PP The cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. -If a pipe table contains a row whose Markdown content is wider than the -column width (see \f[C]--columns\f[R]), then the table will take up the -full text width and the cell contents will wrap, with the relative cell -widths determined by the number of dashes in the line separating the -table header from the table body. +If any line of the markdown source is longer than the column width (see +\f[C]--columns\f[R]), then the table will take up the full text width +and the cell contents will wrap, with the relative cell widths +determined by the number of dashes in the line separating the table +header from the table body. (For example \f[C]---|-\f[R] would make the first column 3/4 and the second column 1/4 of the full text width.) On the other hand, if no lines are wider than column width, then cell @@ -4995,7 +5012,7 @@ instead of \f[R] .fi .PP -This rule is easier to remember than standard Markdown\[cq]s rule, which +This rule is easier to remember than original Markdown\[cq]s rule, which allows only the following characters to be backslash-escaped: .IP .nf @@ -5004,7 +5021,7 @@ allows only the following characters to be backslash-escaped: \f[R] .fi .PP -(However, if the \f[C]markdown_strict\f[R] format is used, the standard +(However, if the \f[C]markdown_strict\f[R] format is used, the original Markdown rule will be used.) .PP A backslash-escaped space is parsed as a nonbreaking space. @@ -5295,7 +5312,7 @@ Note that even if \f[C]raw_html\f[R] is disabled, tables will be rendered with HTML syntax if they cannot use pipe syntax. .SS Extension: \f[C]markdown_in_html_blocks\f[R] .PP -Standard Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of +Original Markdown allows you to include HTML \[lq]blocks\[rq]: 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 @@ -5336,7 +5353,7 @@ There is one exception to this rule: text between \f[C]<script>\f[R], \f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as Markdown. .PP -This departure from standard Markdown should make it easier to mix +This departure from original Markdown should make it easier to mix Markdown with HTML block elements. For example, one can surround a block of Markdown text with \f[C]<div>\f[R] tags without preventing it from being interpreted as @@ -5673,7 +5690,7 @@ One way to do this is to insert a nonbreaking space after the image: .fi .PP Note that in reveal.js slide shows, an image in a paragraph by itself -that has the \f[C]stretch\f[R] class will fill the screen, and the +that has the \f[C]r-stretch\f[R] class will fill the screen, and the caption and figure tags will be omitted. .SS Extension: \f[C]link_attributes\f[R] .PP @@ -6226,7 +6243,7 @@ extra blank space around headings. .PP Include source position attributes when parsing \f[C]commonmark\f[R]. For elements that accept attributes, a \f[C]data-pos\f[R] attribute is -added; other elements are placed in a surrounding Div or Span elemnet +added; other elements are placed in a surrounding Div or Span element with a \f[C]data-pos\f[R] attribute. .SS Extension: \f[C]short_subsuperscripts\f[R] .PP @@ -7534,6 +7551,20 @@ Similarly, for Markdown, external images can be declared with Note that this only works for images; the other media elements have no native representation in pandoc\[cq]s AST and requires the use of raw HTML. +.SS EPUB styling +.PP +By default, pandoc will include some basic styling contained in its +\f[C]epub.css\f[R] data file. +(To see this, use \f[C]pandoc --print-default-data-file epub.css\f[R].) +To use a different CSS file, just use the \f[C]--css\f[R] command line +option. +A few inline styles are defined in addition; these are essential for +correct formatting of pandoc\[cq]s HTML output. +.PP +The \f[C]document-css\f[R] variable may be set if the more opinionated +styling of pandoc\[cq]s default HTML templates is desired (and in that +case the variables defined in Variables for HTML may be used to +fine-tune the style). .SH JUPYTER NOTEBOOKS .PP When creating a Jupyter notebook, pandoc will try to infer the notebook @@ -7941,7 +7972,7 @@ To be safe, you should run all the generated HTML through an HTML sanitizer. .SH AUTHORS .PP -Copyright 2006\[en]2021 John MacFarlane (jgm\[at]berkeley.edu). +Copyright 2006\[en]2022 John MacFarlane (jgm\[at]berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.)