[[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.