path: root/doc
diff options
authorJohn MacFarlane <>2017-10-24 16:08:05 -0700
committerJohn MacFarlane <>2017-10-24 16:08:05 -0700
commit8c0c4f954d21369eef6ec4b1cfb387603e91e985 (patch)
tree78fb5e68bb3259326f5ed808b61bee3381e1e14f /doc
parentb060343ea3f905d884290318e8efd2a33ef87a88 (diff)
Some work on
Diffstat (limited to 'doc')
1 files changed, 42 insertions, 13 deletions
diff --git a/doc/ b/doc/
index aa9ab8c76..75bf227f1 100644
--- a/doc/
+++ b/doc/
@@ -1,13 +1,44 @@
% Using the pandoc API
% John MacFarlane
-intro - pandoc can be used as a library, to write
-your own custom conversion tools, or to power
-a web application.
+Pandoc can be used as a Haskell library, to write your own
+conversion tools or power a web application. This document
+offers an introduction to using the pandoc API.
-# Basic usage
+Detailed API documentation at the level of individual functions
+and types is available at
-a simple example
+# Pandoc's architecture, and a simple example
+Pandoc structure, readers, writers.
+example of using a reader.
+example of using a writer.
+chaining them together.
+# The PandocMonad class
+Pandoc's functions define computations that can be run in
+any instance of the `PandocMonad` typeclass. Two instances
+are provided: `PandocIO` and `PandocPure`. The difference is
+that computations run in `PandocIO` are allowed to do IO
+(for example, read a file), while computations in `PandocPure`
+are free of any side effects. `PandocPure` is useful when
+you want to prevent users from doing anything malicious.
+Here's an example of such a computation, from the module
+-- | Get the verbosity level.
+getVerbosity :: PandocMonad m => m Verbosity
# The Pandoc structure
@@ -19,21 +50,17 @@ getReader, getWriter
# Options
-inc extensions
+various reader and writer options you can set.
# Builder
Inlines vs Inline, etc.
example: report from CSV data
-# The PandocMonad class
-advanced: custom PandocMonad instances
# Templates and other data files
# Handling errors and warnings
@@ -52,6 +79,8 @@ the rest can be left to
+# Custom PandocMonad instances
# Creating a front-end