aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2017-10-24 16:08:05 -0700
committerJohn MacFarlane <jgm@berkeley.edu>2017-10-24 16:08:05 -0700
commit8c0c4f954d21369eef6ec4b1cfb387603e91e985 (patch)
tree78fb5e68bb3259326f5ed808b61bee3381e1e14f
parentb060343ea3f905d884290318e8efd2a33ef87a88 (diff)
downloadpandoc-8c0c4f954d21369eef6ec4b1cfb387603e91e985.tar.gz
Some work on using-the-pandoc-api.md.
-rw-r--r--doc/using-the-pandoc-api.md55
1 files changed, 42 insertions, 13 deletions
diff --git a/doc/using-the-pandoc-api.md b/doc/using-the-pandoc-api.md
index aa9ab8c76..75bf227f1 100644
--- a/doc/using-the-pandoc-api.md
+++ b/doc/using-the-pandoc-api.md
@@ -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
+<https://hackage.haskell.org/package/pandoc>.
-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
+`Text.Pandoc.Class`:
+
+```haskell
+-- | Get the verbosity level.
+getVerbosity :: PandocMonad m => m Verbosity
+```
+
+motivations
+Class.
# The Pandoc structure
@@ -19,21 +50,17 @@ getReader, getWriter
# Options
-inc extensions
+various reader and writer options you can set.
+templates
+extensions
# Builder
Inlines vs Inline, etc.
-monoid
+Monoid
example: report from CSV data
-# The PandocMonad class
-
-motivations
-Class.
-advanced: custom PandocMonad instances
-
# Templates and other data files
# Handling errors and warnings
@@ -52,6 +79,8 @@ the rest can be left to filters.md
# PDF
+# Custom PandocMonad instances
+
# Creating a front-end
Text.Pandoc.App