From e0a994aa22891189f0b87b4d230e43441f5a942a Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Thu, 18 Aug 2022 22:53:58 -0700 Subject: [PATCH] Regenerate man pages. --- MANUAL.txt | 2 +- man/pandoc-server.1 | 280 +++++++++++++++++++++++++------------------- man/pandoc.1 | 18 ++- 3 files changed, 179 insertions(+), 121 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index 362feeb80..998377c00 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: August 3, 2022 +date: August 18, 2022 --- # Synopsis diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 index 4486cca39..15373d35f 100644 --- a/man/pandoc-server.1 +++ b/man/pandoc-server.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 2.18 +.\" Automatically generated by Pandoc 2.19 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. @@ -14,7 +14,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "pandoc-server" "1" "August 15, 2022" "pandoc-server 2.19" "" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc-server 2.19.1" "" .hy .SH SYNOPSIS .PP @@ -24,6 +24,7 @@ \f[V]pandoc-server\f[R] is a web server that can perform pandoc conversions. It can be used either as a running server or as a CGI program. +.PP To use \f[V]pandoc-server\f[R] as a CGI program, rename it (or symlink it) as \f[V]pandoc-server.cgi\f[R]. (Note: if you symlink it, you may need to adjust your webserver\[cq]s @@ -33,7 +34,7 @@ script.) All pandoc functions are run in the PandocPure monad, which ensures that they can do no I/O operations on the server. This should provide a high degree of security. -It does, however, impose certain limitations: +This security does, however, impose certain limitations: .IP \[bu] 2 PDFs cannot be produced. .IP \[bu] 2 @@ -53,6 +54,11 @@ Default: 3030. \f[V]--timeout SECONDS\f[R] Timeout in seconds, after which a conversion is killed. Default: 2. +.RS +.PP +When \f[V]pandoc-server\f[R] is run as a CGI program, this option can be +set via the \f[V]PANDOC_SERVER_TIMEOUT\f[R] environment variable. +.RE .TP \f[V]--help\f[R] Print this help. @@ -97,16 +103,30 @@ the pandoc command line. The output format, possibly with extensions, just as it is specified on the pandoc command line. .TP -\f[V]wrapText\f[R] (\f[V]\[dq]auto\[dq]|\[dq]preserve\[dq]|\[dq]none\[dq]\f[R]) -Text wrapping option: either \f[V]\[dq]auto\[dq]\f[R] (automatic -hard-wrapping to fit within a column width), -\f[V]\[dq]preserve\[dq]\f[R] (insert newlines where they are present in -the source), or \f[V]\[dq]none\[dq]\f[R] (don\[cq]t insert any -unnecessary newlines at all). +\f[V]shift-heading-level-by\f[R] (integer, default 0) +Increase or decrease the level of all headings. .TP -\f[V]columns\f[R] (integer, default 72) -Column width (affects text wrapping and calculation of table column -widths in plain text formats) +\f[V]indented-code-classes\f[R] (array of strings) +List of classes to be applied to indented Markdown code blocks. +.TP +\f[V]default-image-extension\f[R] (string) +Extension to be applied to image sources that lack extensions +(e.g.\ \f[V]\[dq].jpg\[dq]\f[R]). +.TP +\f[V]metadata\f[R] (JSON map) +String-valued metadata. +.TP +\f[V]tab-stop\f[R] (integer, default 4) +Tab stop (spaces per tab). +.TP +\f[V]track-changes\f[R] (\f[V]\[dq]accept\[dq]|\[dq]reject\[dq]|\[dq]all\[dq]\f[R]) +Specifies what to do with insertions, deletions, and comments produced +by the MS Word \[lq]Track Changes\[rq] feature. +Only affects docx input. +.TP +\f[V]abbreviations\f[R] (file path) +List of strings to be regarded as abbreviations when parsing Markdown. +See \f[V]--abbreviations\f[R] in \f[V]pandoc(1)\f[R] for details. .TP \f[V]standalone\f[R] (boolean, default false) If true, causes a standalone document to be produced, using the default @@ -117,95 +137,7 @@ If false, a fragment will be produced. String contents of a document template (see Templates in \f[V]pandoc(1)\f[R] for the format). .TP -\f[V]tabStop\f[R] (integer, default 4) -Tab stop (spaces per tab). -.TP -\f[V]indentedCodeClasses\f[R] (array of strings) -List of classes to be applied to indented Markdown code blocks. -.TP -\f[V]abbreviations\f[R] (array of strings) -List of strings to be regarded as abbreviations when parsing Markdown. -See \f[V]--abbreviations\f[R] in \f[V]pandoc(1)\f[R] for details. -.TP -\f[V]defaultImageExtension\f[R] (string) -Extension to be applied to image sources that lack extensions -(e.g.\ \f[V]\[dq].jpg\[dq]\f[R]). -.TP -\f[V]trackChanges\f[R] (\f[V]\[dq]accept\[dq]|\[dq]reject\[dq]|\[dq]all\[dq]\f[R]) -Specifies what to do with insertions, deletions, and comments produced -by the MS Word \[lq]Track Changes\[rq] feature. -Only affects docx input. -.TP -\f[V]stripComments\f[R] (boolean, default false) -Causes HTML comments to be stripped in Markdown or Textile source, -instead of being passed through to the output format. -.TP -\f[V]citeproc\f[R] (boolean, default false) -Causes citations to be processed using citeproc. -See Citations in \f[V]pandoc(1)\f[R] for details. -.TP -\f[V]citeMethod\f[R] (\f[V]\[dq]citeproc\[dq]|\[dq]natbib\[dq]|\[dq]biblatex\[dq]\f[R]) -Determines how citations are formatted in LaTeX output. -.TP -\f[V]tableOfContents\f[R] (boolean, default false) -Include a table of contents (in supported formats). -.TP -\f[V]tocDepth\f[R] (integer, default 3) -Depth of sections to include in the table of contents. -.TP -\f[V]numberSections\f[R] (boolean, default false) -Automatically number sections (in supported formats). -.TP -\f[V]numberOffset\f[R] (array of integers) -Offsets to be added to each component of the section number. -For example, \f[V][1]\f[R] will cause the first section to be numbered -\[lq]2\[rq] and the first subsection \[lq]2.1\[rq]; \f[V][0,1]\f[R] will -cause the first section to be numbered \[lq]1\[rq] and the first -subsection \[lq]1.2.\[rq] -.TP -\f[V]identifierPrefix\f[R] (string) -Prefix to be added to all automatically-generated identifiers. -.TP -\f[V]sectionDivs\f[R] (boolean, default false) -Arrange the document into a hierarchy of nested sections based on the -headings. -.TP -\f[V]htmlQTags\f[R] (boolean, default false) -Use \f[V]\f[R] elements in HTML instead of literal quotation marks. -.TP -\f[V]listings\f[R] (boolean, default false) -Use the \f[V]listings\f[R] package to format code in LaTeX output. -.TP -\f[V]referenceLinks\f[R] (boolean, default false) -Create reference links rather than inline links in Markdown output. -.TP -\f[V]setextHeaders\f[R] (boolean, default false) -Use Setext (underlined) headings instead of ATX (\f[V]#\f[R]-prefixed) -in Markdown output. -.TP -\f[V]preferAscii\f[R] (boolean, default false) -Use entities and escapes when possible to avoid non-ASCII characters in -the output. -.TP -\f[V]referenceLocation\f[R] (\f[V]\[dq]document\[dq]|\[dq]section\[dq]|\[dq]block\[dq]\f[R]) -Determines whether link references and footnotes are placed at the end -of the document, the end of the section, or the end of the block -(e.g.\ paragraph), in certain formats. -(See \f[V]pandoc(1)\f[R] under \f[V]--reference-location\f[R].) -.TP -\f[V]topLevelDivision\f[R] (\f[V]\[dq]default\[dq]|\[dq]part\[dq]|\[dq]chapter\[dq]|\[dq]section\[dq]\f[R]) -Determines how top-level headings are interpreted in LaTeX, ConTeXt, -DocBook, and TEI. -The \f[V]\[dq]default\[dq]\f[R] value tries to choose the best -interpretation based on heuristics. -.TP -\f[V]emailObfuscation\f[R] (\f[V]\[dq]none\[dq]|\[dq]references\[dq]|\[dq]javascript\[dq]\f[R]) -Determines how email addresses are obfuscated in HTML. -.TP -\f[V]htmlMathMethod\f[R] (\f[V]\[dq]plain\[dq]|\[dq]webtex\[dq]|\[dq]gladtex\[dq]|\[dq]mathml\[dq]|\[dq]mathjax\[dq]|\[dq]katex\[dq]\f[R]) -Determines how math is represented in HTML. -.TP -\f[V]variables\f[R] (JSON mapping) +\f[V]variables\f[R] (JSON map) Variables to be interpolated in the template. (See Templates in \f[V]pandoc(1)\f[R].) .TP @@ -213,15 +145,28 @@ Variables to be interpolated in the template. Dots-per-inch to use for conversions between pixels and other measurements (for image sizes). .TP -\f[V]incremental\f[R] (boolean, default false) -If true, lists appear incrementally by default in slide shows. +\f[V]wrap\f[R] (\f[V]\[dq]auto\[dq]|\[dq]preserve\[dq]|\[dq]none\[dq]\f[R]) +Text wrapping option: either \f[V]\[dq]auto\[dq]\f[R] (automatic +hard-wrapping to fit within a column width), +\f[V]\[dq]preserve\[dq]\f[R] (insert newlines where they are present in +the source), or \f[V]\[dq]none\[dq]\f[R] (don\[cq]t insert any +unnecessary newlines at all). .TP -\f[V]slideLevel\f[R] (integer) -Heading level that deterimes slide divisions in slide shows. -The default is to pick the highest heading level under which there is -body text. +\f[V]columns\f[R] (integer, default 72) +Column width (affects text wrapping and calculation of table column +widths in plain text formats) .TP -\f[V]highlightStyle\f[R] (string, default \f[V]\[dq]pygments\[dq]\f[R]) +\f[V]table-of-contents\f[R] (boolean, default false) +Include a table of contents (in supported formats). +.TP +\f[V]toc-depth\f[R] (integer, default 3) +Depth of sections to include in the table of contents. +.TP +\f[V]strip-comments\f[R] (boolean, default false) +Causes HTML comments to be stripped in Markdown or Textile source, +instead of being passed through to the output format. +.TP +\f[V]highlight-style\f[R] (string, default \f[V]\[dq]pygments\[dq]\f[R]) Specify the style to use for syntax highlighting of code. Standard styles are \f[V]\[dq]pygments\[dq]\f[R] (the default), \f[V]\[dq]kate\[dq]\f[R], \f[V]\[dq]monochrome\[dq]\f[R], @@ -232,23 +177,122 @@ Alternatively, the path of a \f[V].theme\f[R] with a KDE syntax theme may be used (in this case, the relevant file contents must also be included in \f[V]files\f[R], see below). .TP -\f[V]epubMetadata\f[R] (string) -Dublin core XML elements to be used for EPUB metadata. +\f[V]embed-resources\f[R] +Embed images, scripts, styles and other resources in an HTML document +using \f[V]data\f[R] URIs. +Note that this will not work unless the contents of all external +resources are included under \f[V]files\f[R]. .TP -\f[V]epubChapterLevel\f[R] (integer, default 1) -Heading level at which chapter splitting occurs in EPUBs. +\f[V]html-q-tags\f[R] (boolean, default false) +Use \f[V]\f[R] elements in HTML instead of literal quotation marks. .TP -\f[V]epubSubdirectory\f[R] (string, default \[lq]EPUB\[rq]) -Name of content subdirectory in the EPUB container. +\f[V]ascii\f[R] (boolean, default false) +Use entities and escapes when possible to avoid non-ASCII characters in +the output. .TP -\f[V]epubFonts\f[R] (array of file paths) -Fonts to include in the EPUB. -The fonts themselves must be included in \f[V]files\f[R] (see below). +\f[V]reference-links\f[R] (boolean, default false) +Create reference links rather than inline links in Markdown output. .TP -\f[V]referenceDoc\f[R] (file path) +\f[V]reference-location\f[R] (\f[V]\[dq]document\[dq]|\[dq]section\[dq]|\[dq]block\[dq]\f[R]) +Determines whether link references and footnotes are placed at the end +of the document, the end of the section, or the end of the block +(e.g.\ paragraph), in certain formats. +(See \f[V]pandoc(1)\f[R] under \f[V]--reference-location\f[R].) +.TP +\f[V]setext-headers\f[R] (boolean, default false) +Use Setext (underlined) headings instead of ATX (\f[V]#\f[R]-prefixed) +in Markdown output. +.TP +\f[V]top-level-division\f[R] (\f[V]\[dq]default\[dq]|\[dq]part\[dq]|\[dq]chapter\[dq]|\[dq]section\[dq]\f[R]) +Determines how top-level headings are interpreted in LaTeX, ConTeXt, +DocBook, and TEI. +The \f[V]\[dq]default\[dq]\f[R] value tries to choose the best +interpretation based on heuristics. +.TP +\f[V]number-sections\f[R] (boolean, default false) +Automatically number sections (in supported formats). +.TP +\f[V]number-offset\f[R] (array of integers) +Offsets to be added to each component of the section number. +For example, \f[V][1]\f[R] will cause the first section to be numbered +\[lq]2\[rq] and the first subsection \[lq]2.1\[rq]; \f[V][0,1]\f[R] will +cause the first section to be numbered \[lq]1\[rq] and the first +subsection \[lq]1.2.\[rq] +.TP +\f[V]html-math-method\f[R] (\f[V]\[dq]plain\[dq]|\[dq]webtex\[dq]|\[dq]gladtex\[dq]|\[dq]mathml\[dq]|\[dq]mathjax\[dq]|\[dq]katex\[dq]\f[R]) +Determines how math is represented in HTML. +.TP +\f[V]listings\f[R] (boolean, default false) +Use the \f[V]listings\f[R] package to format code in LaTeX output. +.TP +\f[V]incremental\f[R] (boolean, default false) +If true, lists appear incrementally by default in slide shows. +.TP +\f[V]slide-level\f[R] (integer) +Heading level that deterimes slide divisions in slide shows. +The default is to pick the highest heading level under which there is +body text. +.TP +\f[V]section-divs\f[R] (boolean, default false) +Arrange the document into a hierarchy of nested sections based on the +headings. +.TP +\f[V]email-obfuscation\f[R] (\f[V]\[dq]none\[dq]|\[dq]references\[dq]|\[dq]javascript\[dq]\f[R]) +Determines how email addresses are obfuscated in HTML. +.TP +\f[V]identifier-prefix\f[R] (string) +Prefix to be added to all automatically-generated identifiers. +.TP +\f[V]title-prefix\f[R] (string) +Prefix to be added to the title in the HTML header. +.TP +\f[V]reference-doc\f[R] (file path) Reference doc to use in creating \f[V]docx\f[R] or \f[V]odt\f[R] or \f[V]pptx\f[R]. See \f[V]pandoc(1)\f[R] under \f[V]--reference-doc\f[R] for details. +The contents of the file must be included under \f[V]files\f[R]. +.TP +\f[V]epub-cover-image\f[R] (file path) +Cover image for EPUB. +The contents of the file must be included under \f[V]files\f[R]. +.TP +\f[V]epub-metadata\f[R] (file path) +Path of file containing Dublin core XML elements to be used for EPUB +metadata. +The contents of the file must be included under \f[V]files\f[R]. +.TP +\f[V]epub-chapter-level\f[R] (integer, default 1) +Heading level at which chapter splitting occurs in EPUBs. +.TP +\f[V]epub-subdirectory\f[R] (string, default \[lq]EPUB\[rq]) +Name of content subdirectory in the EPUB container. +.TP +\f[V]epub-fonts\f[R] (array of file paths) +Fonts to include in the EPUB. +The fonts themselves must be included in \f[V]files\f[R] (see below). +.TP +\f[V]ipynb-output\f[R] (\f[V]\[dq]best\[dq]|\[dq]all\[dq]|\[dq]none\[dq]\f[R]) +Determines how ipynb output cells are treated. +\f[V]all\f[R] means that all of the data formats included in the +original are preserved. +\f[V]none\f[R] means that the contents of data cells are omitted. +\f[V]best\f[R] causes pandoc to try to pick the richest data block in +each output cell that is compatible with the output format. +.TP +\f[V]citeproc\f[R] (boolean, default false) +Causes citations to be processed using citeproc. +See Citations in \f[V]pandoc(1)\f[R] for details. +.TP +\f[V]bibliography\f[R] (array of file paths) +Files containing bibliographic data. +The contents of the files must be included in \f[V]files\f[R]. +.TP +\f[V]csl\f[R] (file path) +CSL style file. +The contents of the file must be included in \f[V]files\f[R]. +.TP +\f[V]cite-method\f[R] (\f[V]\[dq]citeproc\[dq]|\[dq]natbib\[dq]|\[dq]biblatex\[dq]\f[R]) +Determines how citations are formatted in LaTeX output. .TP \f[V]files\f[R] (JSON mapping of file paths to base64-encoded strings) Any files needed for the conversion, including images referred to in the diff --git a/man/pandoc.1 b/man/pandoc.1 index 077f2412a..b609b5858 100644 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 2.18 +.\" Automatically generated by Pandoc 2.19 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. @@ -14,7 +14,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "Pandoc User\[cq]s Guide" "" "August 3, 2022" "pandoc 2.19" "" +.TH "Pandoc User\[cq]s Guide" "" "August 18, 2022" "pandoc 2.19.1" "" .hy .SH NAME pandoc - general markup converter @@ -7960,6 +7960,20 @@ and the timestamp will be taken from it instead of the current time. Some document formats also include a unique identifier. For EPUB, this can be set explicitly by setting the \f[V]identifier\f[R] metadata field (see EPUB Metadata, above). +.SH RUNNING PANDOC AS A WEB SERVER +.PP +If you rename (or symlink) the pandoc executable to +\f[V]pandoc-server\f[R], it will start up a web server with a JSON API. +This server exposes most of the conversion functionality of pandoc. +For full documentation, see the pandoc-server man page. +.PP +If you rename (or symlink) the pandoc executable to +\f[V]pandoc-server.cgi\f[R], it will function as a CGI program exposing +the same API as \f[V]pandoc-server\f[R]. +.PP +\f[V]pandoc-server\f[R] is designed to be maximally secure; it uses +Haskell\[cq]s type system to provide strong guarantees that no I/O will +be performed on the server during pandoc conversions. .SH A NOTE ON SECURITY .IP "1." 3 Although pandoc itself will not create or modify any files other than