From 0a299a37afd36bec81ce035280da75c963dda603 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Thu, 31 Aug 2023 17:37:46 -0700 Subject: Clean up pandoc-server.1 man page --- man/pandoc-server.1 | 259 ++++++++++++++++++++++++---------------------------- 1 file changed, 121 insertions(+), 138 deletions(-) (limited to 'man') diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 index a3c3db310..c07cd438d 100644 --- a/man/pandoc-server.1 +++ b/man/pandoc-server.1 @@ -1,32 +1,15 @@ -.\" Automatically generated by Pandoc 3.1.5 -.\" -.\" Define V font for inline verbatim, using C font in formats -.\" that render this, and otherwise B font. -.ie "\f[CB]x\f[]"x" \{\ -. ftr V B -. ftr VI BI -. ftr VB B -. ftr VBI BI -.\} -.el \{\ -. ftr V CR -. ftr VI CI -. ftr VB CB -. ftr VBI CBI -.\} -.TH "pandoc-server" "1" "August 15, 2022" "pandoc-server 3.1.6.2" "" -.hy +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.1.7" .SH SYNOPSIS .PP -\f[V]pandoc-server\f[R] [\f[I]options\f[R]] +\f[CR]pandoc-server\f[R] [\f[I]options\f[R]] .SH DESCRIPTION .PP -\f[V]pandoc-server\f[R] is a web server that can perform pandoc +\f[CR]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]. +To use \f[CR]pandoc-server\f[R] as a CGI program, rename it (or symlink +it) as \f[CR]pandoc-server.cgi\f[R]. (Note: if you symlink it, you may need to adjust your webserver\[cq]s configuration in order to allow it to follow symlinks for the CGI script.) @@ -44,44 +27,44 @@ Resources cannot be fetched via HTTP. .IP \[bu] 2 Any images, include files, or other resources needed for the document conversion must be explicitly included in the request, via the -\f[V]files\f[R] field (see below under API). +\f[CR]files\f[R] field (see below under API). .SH OPTIONS .TP -\f[V]--port NUM\f[R] +\f[CR]--port NUM\f[R] HTTP port on which to run the server. Default: 3030. .TP -\f[V]--timeout SECONDS\f[R] +\f[CR]--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. +When \f[CR]pandoc-server\f[R] is run as a CGI program, this option can be +set via the \f[CR]PANDOC_SERVER_TIMEOUT\f[R] environment variable. .RE .TP -\f[V]--help\f[R] +\f[CR]--help\f[R] Print this help. .TP -\f[V]--version\f[R] +\f[CR]--version\f[R] Print version. .SH API .SS Root endpoint .PP -The root (\f[V]/\f[R]) endpoint accepts only POST requests. +The root (\f[CR]/\f[R]) endpoint accepts only POST requests. .SS Response .PP It returns a converted document in one of the following formats (in -order of preference), depending on the \f[V]Accept\f[R] header: +order of preference), depending on the \f[CR]Accept\f[R] header: .IP \[bu] 2 -\f[V]application/octet-stream\f[R] +\f[CR]application/octet-stream\f[R] .IP \[bu] 2 -\f[V]text/plain\f[R] +\f[CR]text/plain\f[R] .IP \[bu] 2 -\f[V]application/json\f[R] +\f[CR]application/json\f[R] .PP -If the result is a binary format (e.g., \f[V]epub\f[R] or -\f[V]docx\f[R]) and the content is returned as plain text or JSON, the +If the result is a binary format (e.g., \f[CR]epub\f[R] or +\f[CR]docx\f[R]) and the content is returned as plain text or JSON, the binary will be base64 encoded. .PP If a JSON response is given, it will have one of the following formats. @@ -115,225 +98,225 @@ Each element of the \[lq]messages\[rq] array will have the format .PP The body of the POST request should be a JSON object, with the following fields. -Only the \f[V]text\f[R] field is required; all of the others can be +Only the \f[CR]text\f[R] field is required; all of the others can be omitted for default values. When there are several string alternatives, the first one given is the default. .TP -\f[V]text\f[R] (string) +\f[CR]text\f[R] (string) The document to be converted. -Note: if the \f[V]from\f[R] format is binary (e.g., \f[V]epub\f[R] or -\f[V]docx\f[R]), then \f[V]text\f[R] should be a base64 encoding of the +Note: if the \f[CR]from\f[R] format is binary (e.g., \f[CR]epub\f[R] or +\f[CR]docx\f[R]), then \f[CR]text\f[R] should be a base64 encoding of the document. .TP -\f[V]from\f[R] (string, default \f[V]\[dq]markdown\[dq]\f[R]) +\f[CR]from\f[R] (string, default \f[CR]\[dq]markdown\[dq]\f[R]) The input format, possibly with extensions, just as it is specified on the pandoc command line. .TP -\f[V]to\f[R] (string, default \f[V]\[dq]html\[dq]\f[R]) +\f[CR]to\f[R] (string, default \f[CR]\[dq]html\[dq]\f[R]) The output format, possibly with extensions, just as it is specified on the pandoc command line. .TP -\f[V]shift-heading-level-by\f[R] (integer, default 0) +\f[CR]shift-heading-level-by\f[R] (integer, default 0) Increase or decrease the level of all headings. .TP -\f[V]indented-code-classes\f[R] (array of strings) +\f[CR]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) +\f[CR]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]). +(e.g.\ \f[CR]\[dq].jpg\[dq]\f[R]). .TP -\f[V]metadata\f[R] (JSON map) +\f[CR]metadata\f[R] (JSON map) String-valued metadata. .TP -\f[V]tab-stop\f[R] (integer, default 4) +\f[CR]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]) +\f[CR]track-changes\f[R] (\f[CR]\[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) +\f[CR]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. +See \f[CR]--abbreviations\f[R] in \f[CR]pandoc(1)\f[R] for details. .TP -\f[V]standalone\f[R] (boolean, default false) +\f[CR]standalone\f[R] (boolean, default false) If true, causes a standalone document to be produced, using the default -template or the custom template specified using \f[V]template\f[R]. +template or the custom template specified using \f[CR]template\f[R]. If false, a fragment will be produced. .TP -\f[V]template\f[R] (string) +\f[CR]template\f[R] (string) String contents of a document template (see Templates in -\f[V]pandoc(1)\f[R] for the format). +\f[CR]pandoc(1)\f[R] for the format). .TP -\f[V]variables\f[R] (JSON map) +\f[CR]variables\f[R] (JSON map) Variables to be interpolated in the template. -(See Templates in \f[V]pandoc(1)\f[R].) +(See Templates in \f[CR]pandoc(1)\f[R].) .TP -\f[V]dpi\f[R] (integer, default 96) +\f[CR]dpi\f[R] (integer, default 96) Dots-per-inch to use for conversions between pixels and other measurements (for image sizes). .TP -\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 +\f[CR]wrap\f[R] (\f[CR]\[dq]auto\[dq]|\[dq]preserve\[dq]|\[dq]none\[dq]\f[R]) +Text wrapping option: either \f[CR]\[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 +\f[CR]\[dq]preserve\[dq]\f[R] (insert newlines where they are present in +the source), or \f[CR]\[dq]none\[dq]\f[R] (don\[cq]t insert any unnecessary newlines at all). .TP -\f[V]columns\f[R] (integer, default 72) +\f[CR]columns\f[R] (integer, default 72) Column width (affects text wrapping and calculation of table column widths in plain text formats) .TP -\f[V]table-of-contents\f[R] (boolean, default false) +\f[CR]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) +\f[CR]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) +\f[CR]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, leave unset for no highlighting) +\f[CR]highlight-style\f[R] (string, leave unset for no highlighting) 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], -\f[V]\[dq]breezeDark\[dq]\f[R], \f[V]\[dq]espresso\[dq]\f[R], -\f[V]\[dq]zenburn\[dq]\f[R], \f[V]\[dq]haddock\[dq]\f[R], and -\f[V]\[dq]tango\[dq]\f[R]. -Alternatively, the path of a \f[V].theme\f[R] with a KDE syntax theme +Standard styles are \f[CR]\[dq]pygments\[dq]\f[R] (the default), +\f[CR]\[dq]kate\[dq]\f[R], \f[CR]\[dq]monochrome\[dq]\f[R], +\f[CR]\[dq]breezeDark\[dq]\f[R], \f[CR]\[dq]espresso\[dq]\f[R], +\f[CR]\[dq]zenburn\[dq]\f[R], \f[CR]\[dq]haddock\[dq]\f[R], and +\f[CR]\[dq]tango\[dq]\f[R]. +Alternatively, the path of a \f[CR].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). +included in \f[CR]files\f[R], see below). .TP -\f[V]embed-resources\f[R] +\f[CR]embed-resources\f[R] Embed images, scripts, styles and other resources in an HTML document -using \f[V]data\f[R] URIs. +using \f[CR]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]. +resources are included under \f[CR]files\f[R]. .TP -\f[V]html-q-tags\f[R] (boolean, default false) -Use \f[V]\f[R] elements in HTML instead of literal quotation marks. +\f[CR]html-q-tags\f[R] (boolean, default false) +Use \f[CR]\f[R] elements in HTML instead of literal quotation marks. .TP -\f[V]ascii\f[R] (boolean, default false) +\f[CR]ascii\f[R] (boolean, default false) Use entities and escapes when possible to avoid non-ASCII characters in the output. .TP -\f[V]reference-links\f[R] (boolean, default false) +\f[CR]reference-links\f[R] (boolean, default false) Create reference links rather than inline links in Markdown output. .TP -\f[V]reference-location\f[R] (\f[V]\[dq]document\[dq]|\[dq]section\[dq]|\[dq]block\[dq]\f[R]) +\f[CR]reference-location\f[R] (\f[CR]\[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].) +(See \f[CR]pandoc(1)\f[R] under \f[CR]--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) +\f[CR]setext-headers\f[R] (boolean, default false) +Use Setext (underlined) headings instead of ATX (\f[CR]#\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]) +\f[CR]top-level-division\f[R] (\f[CR]\[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 +The \f[CR]\[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) +\f[CR]number-sections\f[R] (boolean, default false) Automatically number sections (in supported formats). .TP -\f[V]number-offset\f[R] (array of integers) +\f[CR]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 +For example, \f[CR][1]\f[R] will cause the first section to be numbered +\[lq]2\[rq] and the first subsection \[lq]2.1\[rq]; \f[CR][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]) +\f[CR]html-math-method\f[R] (\f[CR]\[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. +\f[CR]listings\f[R] (boolean, default false) +Use the \f[CR]listings\f[R] package to format code in LaTeX output. .TP -\f[V]incremental\f[R] (boolean, default false) +\f[CR]incremental\f[R] (boolean, default false) If true, lists appear incrementally by default in slide shows. .TP -\f[V]slide-level\f[R] (integer) +\f[CR]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) +\f[CR]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]) +\f[CR]email-obfuscation\f[R] (\f[CR]\[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) +\f[CR]identifier-prefix\f[R] (string) Prefix to be added to all automatically-generated identifiers. .TP -\f[V]title-prefix\f[R] (string) +\f[CR]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]. +\f[CR]reference-doc\f[R] (file path) +Reference doc to use in creating \f[CR]docx\f[R] or \f[CR]odt\f[R] or +\f[CR]pptx\f[R]. +See \f[CR]pandoc(1)\f[R] under \f[CR]--reference-doc\f[R] for details. +The contents of the file must be included under \f[CR]files\f[R]. .TP -\f[V]split-level\f[R] (integer, default 1) +\f[CR]split-level\f[R] (integer, default 1) Heading level at which documents are split in EPUB or chunked HTML. .TP -\f[V]epub-cover-image\f[R] (file path) +\f[CR]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]. +The contents of the file must be included under \f[CR]files\f[R]. .TP -\f[V]epub-metadata\f[R] (file path) +\f[CR]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]. +The contents of the file must be included under \f[CR]files\f[R]. .TP -\f[V]epub-subdirectory\f[R] (string, default \[lq]EPUB\[rq]) +\f[CR]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) +\f[CR]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). +The fonts themselves must be included in \f[CR]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]) +\f[CR]ipynb-output\f[R] (\f[CR]\[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 +\f[CR]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 +\f[CR]none\f[R] means that the contents of data cells are omitted. +\f[CR]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) +\f[CR]citeproc\f[R] (boolean, default false) Causes citations to be processed using citeproc. -See Citations in \f[V]pandoc(1)\f[R] for details. +See Citations in \f[CR]pandoc(1)\f[R] for details. .TP -\f[V]bibliography\f[R] (array of file paths) +\f[CR]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]. +The contents of the files must be included in \f[CR]files\f[R]. .TP -\f[V]csl\f[R] (file path) +\f[CR]csl\f[R] (file path) CSL style file. -The contents of the file must be included in \f[V]files\f[R]. +The contents of the file must be included in \f[CR]files\f[R]. .TP -\f[V]cite-method\f[R] (\f[V]\[dq]citeproc\[dq]|\[dq]natbib\[dq]|\[dq]biblatex\[dq]\f[R]) +\f[CR]cite-method\f[R] (\f[CR]\[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) +\f[CR]files\f[R] (JSON mapping of file paths to base64-encoded strings) Any files needed for the conversion, including images referred to in the document source, should be included here. Binary data must be base64-encoded. Textual data may be left as it is, unless it is \f[I]also\f[R] valid base 64 data, in which case it will be interpreted that way. -.SS \f[V]/batch\f[R] endpoint +.SS \f[CR]/batch\f[R] endpoint .PP -The \f[V]/batch\f[R] endpoint behaves like the root endpoint, except for +The \f[CR]/batch\f[R] endpoint behaves like the root endpoint, except for these two points: .IP \[bu] 2 It accepts a JSON array, each element of which is a JSON object like the @@ -343,27 +326,27 @@ It returns a JSON array of JSON results. .PP This endpoint can be used to convert a sequence of small snippets in one request. -.SS \f[V]/version\f[R] endpoint +.SS \f[CR]/version\f[R] endpoint .PP -The \f[V]/version\f[R] endpoint accepts a GET request and returns the +The \f[CR]/version\f[R] endpoint accepts a GET request and returns the pandoc version as a plain or JSON-encoded string, depending on Accept headers. -.SS \f[V]/babelmark\f[R] endpoint +.SS \f[CR]/babelmark\f[R] endpoint .PP -The \f[V]/babelmark\f[R] endpoint accepts a GET request with the +The \f[CR]/babelmark\f[R] endpoint accepts a GET request with the following query parameters: .IP \[bu] 2 -\f[V]text\f[R] (required string) +\f[CR]text\f[R] (required string) .IP \[bu] 2 -\f[V]from\f[R] (optional string, default is -\f[V]\[dq]markdown\[dq]\f[R]) +\f[CR]from\f[R] (optional string, default is +\f[CR]\[dq]markdown\[dq]\f[R]) .IP \[bu] 2 -\f[V]to\f[R] (optional string, default is \f[V]\[dq]html\[dq]\f[R]) +\f[CR]to\f[R] (optional string, default is \f[CR]\[dq]html\[dq]\f[R]) .IP \[bu] 2 -\f[V]standalone\f[R] (optional boolean, default is \f[V]false\f[R]) +\f[CR]standalone\f[R] (optional boolean, default is \f[CR]false\f[R]) .PP -It returns a JSON object with fields \f[V]html\f[R] and -\f[V]version\f[R]. +It returns a JSON object with fields \f[CR]html\f[R] and +\f[CR]version\f[R]. This endpoint is designed to support the Babelmark website. .SH AUTHORS .PP -- cgit v1.2.3