From 3f2b44b694af2af42468b03437db70b24d6263df Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Mon, 15 Aug 2022 09:51:17 -0700 Subject: [PATCH] Beginning of man page for pandoc-server. --- Makefile | 6 ++ RELEASE-CHECKLIST | 2 +- man/pandoc-server.1 | 160 ++++++++++++++++++++++++++++++++++++++++ server/pandoc-server.md | 149 +++++++++++++++++++++++++++++++++++++ 4 files changed, 316 insertions(+), 1 deletion(-) create mode 100644 man/pandoc-server.1 create mode 100644 server/pandoc-server.md diff --git a/Makefile b/Makefile index b14818c2c..dab193fe5 100644 --- a/Makefile +++ b/Makefile @@ -99,6 +99,12 @@ man/pandoc.1: MANUAL.txt man/pandoc.1.before man/pandoc.1.after --variable footer="pandoc $(version)" \ -o $@ +man/pandoc-server.1: server/pandoc-server.md + pandoc $< -f markdown -t man -s \ + --lua-filter man/manfilter.lua \ + --variable footer="pandoc-server $(version)" \ + -o $@ + README.md: README.template MANUAL.txt tools/update-readme.lua pandoc --lua-filter tools/update-readme.lua \ --reference-location=section -t gfm $< -o $@ diff --git a/RELEASE-CHECKLIST b/RELEASE-CHECKLIST index c5fcce7d3..429ac7fd7 100644 --- a/RELEASE-CHECKLIST +++ b/RELEASE-CHECKLIST @@ -1,6 +1,6 @@ [ ] make check [ ] make README.md and commit if needed -[ ] make man/pandoc.1 and commit if needed +[ ] make man/pandoc.1 and man/pandoc-server.1 and commit if needed [ ] Finalize changelog [ ] Update AUTHORS [ ] push release candidate branch rc/VERSION and (if it builds diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 new file mode 100644 index 000000000..20602d5c9 --- /dev/null +++ b/man/pandoc-server.1 @@ -0,0 +1,160 @@ +.\" Automatically generated by Pandoc 2.18 +.\" +.\" 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 2.19" "" +.hy +.SH SYNOPSIS +.PP +\f[V]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 +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]. +.SH OPTIONS +.TP +\f[V]--port NUM\f[R] +HTTP port on which to run the server. +Default: 3030. +.TP +\f[V]--timeout SECONDS\f[R] +Timeout in seconds, after which a conversion is killed. +Default: 2. +.TP +\f[V]--help\f[R] +Help +.SH API +.SS Root endpoint +.PP +The root (\f[V]/\f[R]) endpoint accepts only POST requests. +It returns a converted document in one of the following formats, +depending on Accept headers: +.IP \[bu] 2 +\f[V]text/plain\f[R] +.IP \[bu] 2 +\f[V]application/json\f[R] +.IP \[bu] 2 +\f[V]application/octet-stream\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 +binary will be base64 encoded. +.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 +omitted for default values. +.TP +\f[V]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 +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 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 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 +.SS \f[V]/batch\f[R] endpoint +.PP +The \f[V]/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 +one expected by the root endpoint. +.IP \[bu] 2 +It returns a JSON array of results. +(It will not return plain text or octet-stream, like the root endpoint.) +.PP +This endpoint can be used to convert a sequence of small snippets in one +request. +.SS \f[V]/version\f[R] endpoint +.PP +The \f[V]/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 +.PP +The \f[V]/babelmark\f[R] endpoint accepts a GET request with the +following query parameters: +.IP \[bu] 2 +\f[V]text\f[R] (required string) +.IP \[bu] 2 +\f[V]from\f[R] (optional string, default is +\f[V]\[dq]markdown\[dq]\f[R]) +.IP \[bu] 2 +\f[V]to\f[R] (optional string, default is \f[V]\[dq]html\[dq]\f[R]) +.IP \[bu] 2 +\f[V]standalone\f[R] (optional boolean, default is \f[V]false\f[R]) +.PP +It returns a JSON object with fields \f[V]html\f[R] and +\f[V]version\f[R]. +This endpoint is designed to support the +Babelmarkhttps://babelmark.github.io website. +.SH AUTHORS +.PP +Copyright 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.) diff --git a/server/pandoc-server.md b/server/pandoc-server.md new file mode 100644 index 000000000..6d7961ee4 --- /dev/null +++ b/server/pandoc-server.md @@ -0,0 +1,149 @@ +--- +title: pandoc-server +section: 1 +date: August 15, 2022 +--- + +# SYNOPSIS + +`pandoc-server` [*options*] + +# DESCRIPTION + +`pandoc-server` 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 `pandoc-server` as a CGI +program, rename it as `pandoc-server.cgi`. + +# OPTIONS + +`--port NUM` +: HTTP port on which to run the server. Default: 3030. + +`--timeout SECONDS` +: Timeout in seconds, after which a conversion is killed. Default: 2. + +`--help` +: Help + +# API + +## Root endpoint + +The root (`/`) endpoint accepts only POST requests. +It returns a converted document in one of the following +formats, depending on Accept headers: + +- `text/plain` +- `application/json` +- `application/octet-stream` + +If the result is a binary format (e.g., `epub` or `docx`) +and the content is returned as plain text or JSON, the +binary will be base64 encoded. + +The body of the POST request should be a JSON object, +with the following fields. Only the `text` field is +required; all of the others can be omitted for default +values. + +`text` (string) + +: 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 + specified on the pandoc command line. + +`to` (string, default `"html"`) + +: the output format, possibly with extensions, just as it is + specified on the pandoc command line. + + +``` TODO +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)] +``` + +## `/batch` endpoint + +The `/batch` endpoint behaves like the root endpoint, +except for these two points: + +- It accepts a JSON array, each element of which is a JSON + object like the one expected by the root endpoint. +- It returns a JSON array of results. (It will not return + plain text or octet-stream, like the root endpoint.) + +This endpoint can be used to convert a sequence of small +snippets in one request. + +## `/version` endpoint + +The `/version` endpoint accepts a GET request and returns +the pandoc version as a plain or JSON-encoded string, +depending on Accept headers. + +## `/babelmark` endpoint + +The `/babelmark` endpoint accepts a GET request with +the following query parameters: + +- `text` (required string) +- `from` (optional string, default is `"markdown"`) +- `to` (optional string, default is `"html"`) +- `standalone` (optional boolean, default is `false`) + +It returns a JSON object with fields `html` and `version`. +This endpoint is designed to support the +[Babelmark]()https://babelmark.github.io website. + +# AUTHORS + +Copyright 2022 John MacFarlane (jgm@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.) + +[GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License" +