Some work on using-the-pandoc-api.md.

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