Beginning of man page for pandoc-server.

4 files changed, 316 insertions, 1 deletions

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 ([email protected]). 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"
+