Beginning of man page for pandoc-server.
This commit is contained in:
John MacFarlane
parent
87daaa37a9
commit
3f2b44b694
4 changed files with 316 additions and 1 deletions
6
Makefile
6
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 $@
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
160
man/pandoc-server.1
Normal file
160
man/pandoc-server.1
Normal file
|
|
@ -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.)
|
||||
149
server/pandoc-server.md
Normal file
149
server/pandoc-server.md
Normal file
|
|
@ -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"
|
||||
|
||||
Loading…
Reference in a new issue