Changeset 40424 in project


Ignore:
Timestamp:
09/05/21 11:47:39 (3 weeks ago)
Author:
lassik
Message:

Update to reflect changed API

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/pandoc

    r40392 r40424  
    1515syntax tree.
    1616
    17 === Documentation
     17Pandoc can be called the following ways:
    1818
    19 <parameter>(pandoc-command-line [string-list])</parameter>
     19* The official {{pandoc}} command.
     20* The unofficial {{pandoc-tar}} command.
     21* The unofficial {{pandoc-server}} via HTTP.
    2022
    21 This parameter lets the user customize the command line that is given
    22 to the operating system to run Pandoc. All Pandoc invocations start
    23 with this command line. The default is {{'("pandoc")}}.
     23=== The (pandoc) library
    2424
    25 Treat this parameter like RnRS {{command-line}}: shell syntax cannot
    26 be used, and command line arguments should not be shell-quoted.
     25<procedure>(pandoc-bytevectors->json pandoc input-format bytevectors)</procedure>
     26<procedure>(pandoc-bytevectors->sxml pandoc input-format bytevectors)</procedure>
    2727
    28 <procedure>(pandoc-port->json input-format input-port)</procedure>
    29 <procedure>(pandoc-file->json input-format input-filename)</procedure>
     28<procedure>(pandoc-bytevector->json pandoc input-format bytevector)</procedure>
     29<procedure>(pandoc-bytevector->sxml pandoc input-format bytevector)</procedure>
    3030
    31 These procedures return Pandoc's JSON parse tree. The JSON is decoded
    32 into the canonical Scheme JSON representation used by SRFI 180, the
    33 {{cjson}} and {{medea}} eggs, etc.: JSON arrays become Scheme vectors,
    34 JSON objects become Scheme association lists with symbol keys, and
    35 JSON null becomes the symbol {{'null}}.
     31<procedure>(pandoc-strings->json pandoc input-format strings)</procedure>
     32<procedure>(pandoc-strings->sxml pandoc input-format strings)</procedure>
    3633
    37 The {{input-format}} argument is a symbol, and is supplied as Pandoc's
    38 {{--from}} argument.
     34<procedure>(pandoc-string->json pandoc input-format string)</procedure>
     35<procedure>(pandoc-string->sxml pandoc input-format string)</procedure>
     36
     37<procedure>(pandoc-files->json pandoc input-format filenames)</procedure>
     38<procedure>(pandoc-files->sxml pandoc input-format filenames)</procedure>
     39
     40<procedure>(pandoc-file->json pandoc input-format filename)</procedure>
     41<procedure>(pandoc-file->sxml pandoc input-format filename)</procedure>
     42
     43<procedure>(pandoc-port->json pandoc input-format port)</procedure>
     44<procedure>(pandoc-port->sxml pandoc input-format port)</procedure>
     45
     46These procedures parse markup from various sources.
     47
     48The {{pandoc}} argument is the Pandoc endpoint to use: cli, tar, or
     49server. The next sections explain how to create endpoints.
     50
     51The {{->json}} procedures return Pandoc's JSON parse tree. The JSON is
     52decoded into the canonical Scheme JSON representation used by SRFI
     53180, the {{cjson}} and {{medea}} eggs, etc.: JSON arrays become Scheme
     54vectors, JSON objects become Scheme association lists with symbol
     55keys, and JSON null becomes the symbol {{'null}}.
     56
     57The {{->sxml}} procedures are like their {{->json}} counterparts, but
     58instead of JSON they return an SXML conversion of Pandoc's parse tree
     59using HTML tags. The parse tree is easy to turn into HTML using one of
     60several Scheme libraries, e.g. Chicken's {{sxml-transforms}} egg.
     61
     62The {{input-format}} argument is a symbol, e.g. {{markdown}} or
     63{{html}}, and is supplied as Pandoc's {{--from}} argument or its
     64equivalent for the given endpoint.
    3965
    4066An exception is raised if the conversion is not successful.
    4167
    42 <procedure>(pandoc-port->sxml input-format input-port)</procedure>
    43 <procedure>(pandoc-file->sxml input-format input-filename)</procedure>
     68<procedure>(pandoc-json->sxml json)</procedure>
    4469
    45 These procedures are like their {{->json}} counterparts, but instead
    46 of JSON they return an SXML conversion of Pandoc's parse tree using
    47 HTML tags. The parse tree is easy to turn into HTML using one of
    48 several Scheme libraries, e.g. Chicken's {{sxml-transforms}} egg.
     70This is a utility procedure that parses JSON into SXML. You probably
     71don't need this, but you might, so it's exported anyway.
    4972
    50 === Caveats
     73=== The (pandoc cli) library
    5174
    52 Pandoc can be quite slow, but its work could be easily parallelized by
    53 running one instance of Pandoc per document.
     75<procedure>(pandoc-cli [command-name])</procedure>
     76
     77Create a pandoc endpoint using the official {{pandoc}} command line
     78interface. The default {{command-name}} is {{"pandoc"}}.
     79
     80Note that documents are converted serially, and a separate Pandoc
     81instance is launched for each document, making batch conversions slow.
     82We tried launching several Pandoc instances in parallel, but it
     83doesn't materially decrease the conversion time. The tar and server
     84endpoints can avoid this problem by sending an entire batch of
     85documents to the same Pandoc instance all at once, which is something
     86that the official CLI does not support.
     87
     88Try [[https://repology.org/project/pandoc/versions|pandoc at
     89Repology]] to find a Pandoc package for your operating system.
     90
     91=== The (pandoc tar) library
     92
     93<procedure>(pandoc-tar [command-name])</procedure>
     94
     95Create a pandoc endpoint using the unofficial {{pandoc-tar}} command
     96line interface. The default {{command-name}} is {{"pandoc-tar"}}.
     97
     98See the [[https://github.com/lassik/pandoc-tar|pandoc-tar homepage]]
     99for installation instructions.
     100
     101=== The (pandoc server) library
     102
     103<procedure>(pandoc-server base-url)</procedure>
     104
     105Create a pandoc endpoint using the unofficial {{pandoc-server}} HTTP
     106REST API. Give a {{base-url}} like {{"http://localhost:8080/"}}.
     107
     108See the [[https://github.com/jgm/pandoc-server|pandoc-server
     109homepage]] for installation instructions.
    54110
    55111=== Version History
    56112
    57 * 0.1: First release
     113* 0.2: Redo the API. Add tar and server endpoints.
     114* 0.1: First release.
    58115
    59116=== Author
     
    69126
    70127  Copyright 2020 Lassi Kortela
    71  
     128
    72129  Permission to use, copy, modify, and distribute this software for any
    73130  purpose with or without fee is hereby granted, provided that the above
    74131  copyright notice and this permission notice appear in all copies.
    75  
     132
    76133  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
    77134  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
Note: See TracChangeset for help on using the changeset viewer.