From c5f8a38f38aa20da77042b0a6c984e8f74db855a Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Tue, 16 Aug 2022 16:11:04 -0700 Subject: [PATCH] Finished pandoc-server documentation. --- man/pandoc-server.1 | 238 +++++++++++++++++++++++++++++++--------- server/pandoc-server.md | 106 ++++++++++-------- 2 files changed, 252 insertions(+), 92 deletions(-) diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 index 20602d5c9..4486cca39 100644 --- a/man/pandoc-server.1 +++ b/man/pandoc-server.1 @@ -24,8 +24,26 @@ \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. -To use \f[V]pandoc-server\f[R] as a CGI program, rename it as -\f[V]pandoc-server.cgi\f[R]. +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 +configuration in order to allow it to follow symlinks for the CGI +script.) +.PP +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: +.IP \[bu] 2 +PDFs cannot be produced. +.IP \[bu] 2 +Filters are not supported. +.IP \[bu] 2 +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). .SH OPTIONS .TP \f[V]--port NUM\f[R] @@ -37,7 +55,10 @@ Timeout in seconds, after which a conversion is killed. Default: 2. .TP \f[V]--help\f[R] -Help +Print this help. +.TP +\f[V]--version\f[R] +Print version. .SH API .SS Root endpoint .PP @@ -59,63 +80,182 @@ 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 omitted for default values. +When there are several string alternatives, the first one given is the +default. .TP \f[V]text\f[R] (string) -the document to be converted. +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 document. .TP \f[V]from\f[R] (string, default \f[V]\[dq]markdown\[dq]\f[R]) -the input format, possibly with extensions, just as it is specified on +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]) -the output format, possibly with extensions, just as it is specified on +The output format, possibly with extensions, just as it is specified on the pandoc command line. -.IP -.nf -\f[C] -wrapText :: Maybe WrapOption -columns :: Maybe Int -standalone :: Maybe Bool -template :: Maybe Text -tabStop :: Maybe Int -indentedCodeClasses :: Maybe [Text] -abbreviations :: Maybe (Set Text) -defaultImageExtension :: Maybe Text -trackChanges :: Maybe TrackChanges -stripComments :: Maybe Bool -citeproc :: Maybe Bool -variables :: Maybe (DocTemplates.Context Text) -tableOfContents :: Maybe Bool -incremental :: Maybe Bool -htmlMathMethod :: Maybe HTMLMathMethod -numberSections :: Maybe Bool -numberOffset :: Maybe [Int] -sectionDivs :: Maybe Bool -referenceLinks :: Maybe Bool -dpi :: Maybe Int -emailObfuscation :: Maybe ObfuscationMethod -identifierPrefix :: Maybe Text -citeMethod :: Maybe CiteMethod -htmlQTags :: Maybe Bool -slideLevel :: Maybe Int -topLevelDivision :: Maybe TopLevelDivision -listings :: Maybe Bool -highlightStyle :: Maybe Text -setextHeaders :: Maybe Bool -epubSubdirectory :: Maybe Text -epubFonts :: Maybe [FilePath] -epubMetadata :: Maybe Text -epubChapterLevel :: Maybe Int -tocDepth :: Maybe Int -referenceDoc :: Maybe FilePath -referenceLocation :: Maybe ReferenceLocation -preferAscii :: Maybe Bool -files :: Maybe [(FilePath, Blob)] -\f[R] -.fi +.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). +.TP +\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]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]. +If false, a fragment will be produced. +.TP +\f[V]template\f[R] (string) +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) +Variables to be interpolated in the template. +(See Templates in \f[V]pandoc(1)\f[R].) +.TP +\f[V]dpi\f[R] (integer, default 96) +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. +.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. +.TP +\f[V]highlightStyle\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], +\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 +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. +.TP +\f[V]epubChapterLevel\f[R] (integer, default 1) +Heading level at which chapter splitting occurs in EPUBs. +.TP +\f[V]epubSubdirectory\f[R] (string, default \[lq]EPUB\[rq]) +Name of content subdirectory in the EPUB container. +.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). +.TP +\f[V]referenceDoc\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. +.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 +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 .PP The \f[V]/batch\f[R] endpoint behaves like the root endpoint, except for diff --git a/server/pandoc-server.md b/server/pandoc-server.md index 60467bcad..e22063fa8 100644 --- a/server/pandoc-server.md +++ b/server/pandoc-server.md @@ -71,97 +71,97 @@ the first one given is the default. `text` (string) -: the document to be converted. Note: +: The document to be converted. Note: if the `from` format is binary (e.g., `epub` or `docx`), then `text` should be a base64 encoding of the document. `from` (string, default `"markdown"`) -: the input format, possibly with extensions, just as it is +: The input format, possibly with extensions, just as it is specified on the pandoc command line. `to` (string, default `"html"`) -: the output format, possibly with extensions, just as it is +: The output format, possibly with extensions, just as it is specified on the pandoc command line. `wrapText` (`"auto"|"preserve"|"none"`) -: text wrapping option: either `"auto"` (automatic +: Text wrapping option: either `"auto"` (automatic hard-wrapping to fit within a column width), `"preserve"` (insert newlines where they are present in the source), or `"none"` (don't insert any unnecessary newlines at all). `columns` (integer, default 72) -: column width (affects text wrapping and calculation of +: Column width (affects text wrapping and calculation of table column widths in plain text formats) `standalone` (boolean, default false) -: if true, causes a standalone document to be produced, using +: If true, causes a standalone document to be produced, using the default template or the custom template specified using `template`. If false, a fragment will be produced. `template` (string) -: string contents of a document template (see Templates in +: String contents of a document template (see Templates in `pandoc(1)` for the format). `tabStop` (integer, default 4) -: tab stop (spaces per tab). +: Tab stop (spaces per tab). `indentedCodeClasses` (array of strings) -: list of classes to be applied to indented Markdown code blocks. +: List of classes to be applied to indented Markdown code blocks. `abbreviations` (array of strings) -: list of strings to be regarded as abbreviations when +: List of strings to be regarded as abbreviations when parsing Markdown. See `--abbreviations` in `pandoc(1)` for details. `defaultImageExtension` (string) -: extension to be applied to image sources that lack extensions +: Extension to be applied to image sources that lack extensions (e.g. `".jpg"`). `trackChanges` (`"accept"|"reject"|"all"`) -: specifies what to do with insertions, deletions, and +: Specifies what to do with insertions, deletions, and comments produced by the MS Word "Track Changes" feature. Only affects docx input. `stripComments` (boolean, default false) -: causes HTML comments to be stripped in Markdown or Textile +: Causes HTML comments to be stripped in Markdown or Textile source, instead of being passed through to the output format. `citeproc` (boolean, default false) -: causes citations to be processed using citeproc. See +: Causes citations to be processed using citeproc. See Citations in `pandoc(1)` for details. `citeMethod` (`"citeproc"|"natbib"|"biblatex"`) -: determines how citations are formatted in LaTeX output. +: Determines how citations are formatted in LaTeX output. `tableOfContents` (boolean, default false) -: include a table of contents (in supported formats). +: Include a table of contents (in supported formats). `tocDepth` (integer, default 3) -: depth of sections to include in the table of contents. +: Depth of sections to include in the table of contents. `numberSections` (boolean, default false) -: automatically number sections (in supported formats). +: Automatically number sections (in supported formats). `numberOffset` (array of integers) -: offsets to be added to each component of the section number. +: Offsets to be added to each component of the section number. For example, `[1]` will cause the first section to be numbered "2" and the first subsection "2.1"; `[0,1]` will cause the first section to be numbered "1" and the first @@ -169,96 +169,116 @@ the first one given is the default. `identifierPrefix` (string) -: prefix to be added to all automatically-generated identifiers. +: Prefix to be added to all automatically-generated identifiers. `sectionDivs` (boolean, default false) -: arrange the document into a hierarchy of nested sections +: Arrange the document into a hierarchy of nested sections based on the headings. `htmlQTags` (boolean, default false) -: use `` elements in HTML instead of literal quotation marks. +: Use `` elements in HTML instead of literal quotation marks. `listings` (boolean, default false) -: use the `listings` package to format code in LaTeX output. +: Use the `listings` package to format code in LaTeX output. `referenceLinks` (boolean, default false) -: create reference links rather than inline links in Markdown output. +: Create reference links rather than inline links in Markdown output. `setextHeaders` (boolean, default false) -: use Setext (underlined) headings instead of ATX (`#`-prefixed) +: Use Setext (underlined) headings instead of ATX (`#`-prefixed) in Markdown output. `preferAscii` (boolean, default false) -: use entities and escapes when possible to avoid non-ASCII +: Use entities and escapes when possible to avoid non-ASCII characters in the output. -`referenceLocation` (`"document"|"block"|"section"`) +`referenceLocation` (`"document"|"section"|"block"`) -: +: 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 `pandoc(1)` under `--reference-location`.) `topLevelDivision` (`"default"|"part"|"chapter"|"section"`) -: +: Determines how top-level headings are interpreted in + LaTeX, ConTeXt, DocBook, and TEI. The `"default"` value + tries to choose the best interpretation based on heuristics. `emailObfuscation` (`"none"|"references"|"javascript"`) -: +: Determines how email addresses are obfuscated in HTML. `htmlMathMethod` (`"plain"|"webtex"|"gladtex"|"mathml"|"mathjax"|"katex"`) -: +: Determines how math is represented in HTML. `variables` (JSON mapping) -: +: Variables to be interpolated in the template. (See Templates + in `pandoc(1)`.) `dpi` (integer, default 96) -: +: Dots-per-inch to use for conversions between pixels and + other measurements (for image sizes). `incremental` (boolean, default false) -: +: If true, lists appear incrementally by default in slide shows. `slideLevel` (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. `highlightStyle` (string, default `"pygments"`) -: pygments (the default), kate, monochrome, breezeDark, -espresso, zenburn, haddock, and tango or .theme file +: Specify the style to use for syntax highlighting of code. + Standard styles are `"pygments"` (the default), `"kate"`, + `"monochrome"`, `"breezeDark"`, `"espresso"`, `"zenburn"`, + `"haddock"`, and `"tango"`. Alternatively, the path of + a `.theme` with a KDE syntax theme may be used (in this + case, the relevant file contents must also be included + in `files`, see below). `epubMetadata` (string) -: +: Dublin core XML elements to be used for EPUB metadata. `epubChapterLevel` (integer, default 1) -: +: Heading level at which chapter splitting occurs in EPUBs. `epubSubdirectory` (string, default "EPUB") -: +: Name of content subdirectory in the EPUB container. `epubFonts` (array of file paths) -: +: Fonts to include in the EPUB. The fonts themselves must be + included in `files` (see below). `referenceDoc` (file path) -: +: Reference doc to use in creating `docx` or `odt` or `pptx`. + See `pandoc(1)` under `--reference-doc` for details. `files` (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 *also* valid base 64 data, + in which case it will be interpreted that way. ## `/batch` endpoint