141 lines
5.1 KiB
Plaintext
141 lines
5.1 KiB
Plaintext
[[tags: egg]]
|
|
|
|
== pandoc
|
|
|
|
[[toc:]]
|
|
|
|
=== Introduction
|
|
|
|
This egg provides a Scheme interface to
|
|
[[https://pandoc.org/|Pandoc]], the universal document converter.
|
|
|
|
Pandoc can convert documents between several markup languages
|
|
(Markdown, AsciiDoc, etc.) It fits all of those languages into a
|
|
uniform syntax tree. This egg supplies JSON and SXML versions of the
|
|
syntax tree.
|
|
|
|
Pandoc can be called the following ways:
|
|
|
|
* The official {{pandoc}} command.
|
|
* The unofficial {{pandoc-tar}} command.
|
|
* The unofficial {{pandoc-server}} via HTTP.
|
|
|
|
=== The (pandoc) library
|
|
|
|
<procedure>(pandoc-bytevectors->json pandoc input-format bytevectors)</procedure>
|
|
<procedure>(pandoc-bytevectors->sxml pandoc input-format bytevectors)</procedure>
|
|
|
|
<procedure>(pandoc-bytevector->json pandoc input-format bytevector)</procedure>
|
|
<procedure>(pandoc-bytevector->sxml pandoc input-format bytevector)</procedure>
|
|
|
|
<procedure>(pandoc-strings->json pandoc input-format strings)</procedure>
|
|
<procedure>(pandoc-strings->sxml pandoc input-format strings)</procedure>
|
|
|
|
<procedure>(pandoc-string->json pandoc input-format string)</procedure>
|
|
<procedure>(pandoc-string->sxml pandoc input-format string)</procedure>
|
|
|
|
<procedure>(pandoc-files->json pandoc input-format filenames)</procedure>
|
|
<procedure>(pandoc-files->sxml pandoc input-format filenames)</procedure>
|
|
|
|
<procedure>(pandoc-file->json pandoc input-format filename)</procedure>
|
|
<procedure>(pandoc-file->sxml pandoc input-format filename)</procedure>
|
|
|
|
<procedure>(pandoc-port->json pandoc input-format port)</procedure>
|
|
<procedure>(pandoc-port->sxml pandoc input-format port)</procedure>
|
|
|
|
These procedures parse markup from various sources.
|
|
|
|
The {{pandoc}} argument is the Pandoc endpoint to use: cli, tar, or
|
|
server. The next sections explain how to create endpoints.
|
|
|
|
The {{->json}} procedures return Pandoc's JSON parse tree. The JSON is
|
|
decoded into the canonical Scheme JSON representation used by SRFI
|
|
180, the {{cjson}} and {{medea}} eggs, etc.: JSON arrays become Scheme
|
|
vectors, JSON objects become Scheme association lists with symbol
|
|
keys, and JSON null becomes the symbol {{'null}}.
|
|
|
|
The {{->sxml}} procedures are like their {{->json}} counterparts, but
|
|
instead of JSON they return an SXML conversion of Pandoc's parse tree
|
|
using HTML tags. The parse tree is easy to turn into HTML using one of
|
|
several Scheme libraries, e.g. Chicken's {{sxml-transforms}} egg.
|
|
|
|
The {{input-format}} argument is a symbol, e.g. {{markdown}} or
|
|
{{html}}, and is supplied as Pandoc's {{--from}} argument or its
|
|
equivalent for the given endpoint.
|
|
|
|
An exception is raised if the conversion is not successful.
|
|
|
|
<procedure>(pandoc-json->sxml json)</procedure>
|
|
|
|
This is a utility procedure that parses JSON into SXML. You probably
|
|
don't need this, but you might, so it's exported anyway.
|
|
|
|
=== The (pandoc cli) library
|
|
|
|
<procedure>(pandoc-cli [command-name])</procedure>
|
|
|
|
Create a pandoc endpoint using the official {{pandoc}} command line
|
|
interface. The default {{command-name}} is {{"pandoc"}}.
|
|
|
|
Note that documents are converted serially, and a separate Pandoc
|
|
instance is launched for each document, making batch conversions slow.
|
|
We tried launching several Pandoc instances in parallel, but it
|
|
doesn't materially decrease the conversion time. The tar and server
|
|
endpoints can avoid this problem by sending an entire batch of
|
|
documents to the same Pandoc instance all at once, which is something
|
|
that the official CLI does not support.
|
|
|
|
Try [[https://repology.org/project/pandoc/versions|pandoc at
|
|
Repology]] to find a Pandoc package for your operating system.
|
|
|
|
=== The (pandoc tar) library
|
|
|
|
<procedure>(pandoc-tar [command-name])</procedure>
|
|
|
|
Create a pandoc endpoint using the unofficial {{pandoc-tar}} command
|
|
line interface. The default {{command-name}} is {{"pandoc-tar"}}.
|
|
|
|
See the [[https://github.com/lassik/pandoc-tar|pandoc-tar homepage]]
|
|
for installation instructions.
|
|
|
|
=== The (pandoc server) library
|
|
|
|
<procedure>(pandoc-server base-url)</procedure>
|
|
|
|
Create a pandoc endpoint using the unofficial {{pandoc-server}} HTTP
|
|
REST API. Give a {{base-url}} like {{"http://localhost:8080/"}}.
|
|
|
|
See the [[https://github.com/jgm/pandoc-server|pandoc-server
|
|
homepage]] for installation instructions.
|
|
|
|
=== Version History
|
|
|
|
* 0.2: Redo the API. Add tar and server endpoints.
|
|
* 0.1: First release.
|
|
|
|
=== Author
|
|
|
|
Lassi Kortela
|
|
|
|
=== Repository
|
|
|
|
[[https://github.com/lassik/scheme-pandoc|
|
|
https://github.com/lassik/scheme-pandoc]]
|
|
|
|
=== License
|
|
|
|
Copyright 2020 Lassi Kortela
|
|
|
|
Permission to use, copy, modify, and distribute this software for any
|
|
purpose with or without fee is hereby granted, provided that the above
|
|
copyright notice and this permission notice appear in all copies.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
|
|
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
|
|
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
|
|
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
|
|
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
|
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
PERFORMANCE OF THIS SOFTWARE.
|