@@ -1,13 +1,44 @@
11% Using the pandoc API
22% John MacFarlane
33
4−intro - pandoc can be used as a library, to write
5−your own custom conversion tools, or to power
6−a web application.
4+Pandoc can be used as a Haskell library, to write your own
5+conversion tools or power a web application. This document
6+offers an introduction to using the pandoc API.
77
8−# Basic usage
8+Detailed API documentation at the level of individual functions
9+and types is available at
10+<https://hackage.haskell.org/package/pandoc>.
911
10−a simple example
12+# Pandoc's architecture, and a simple example
13+
14+Pandoc structure, readers, writers.
15+
16+example of using a reader.
17+
18+example of using a writer.
19+
20+chaining them together.
21+
22+# The PandocMonad class
23+
24+Pandoc's functions define computations that can be run in
25+any instance of the `PandocMonad` typeclass. Two instances
26+are provided: `PandocIO` and `PandocPure`. The difference is
27+that computations run in `PandocIO` are allowed to do IO
28+(for example, read a file), while computations in `PandocPure`
29+are free of any side effects. `PandocPure` is useful when
30+you want to prevent users from doing anything malicious.
31+
32+Here's an example of such a computation, from the module
33+`Text.Pandoc.Class`:
34+
35+```haskell
36+-- | Get the verbosity level.
37+getVerbosity :: PandocMonad m => m Verbosity
38+```
39+
40+motivations
41+Class.
1142
1243# The Pandoc structure
1344
@@ -19,21 +50,17 @@ getReader, getWriter
1950
2051# Options
2152
22−inc extensions
53+various reader and writer options you can set.
54+templates
55+extensions
2356
2457# Builder
2558
2659Inlines vs Inline, etc.
27−monoid
60+Monoid
2861
2962example: report from CSV data
3063
31−# The PandocMonad class
32−
33−motivations
34−Class.
35−advanced: custom PandocMonad instances
36−
3764# Templates and other data files
3865
3966# Handling errors and warnings
@@ -52,6 +79,8 @@ the rest can be left to filters.md
5279
5380# PDF
5481
82+# Custom PandocMonad instances
83+
5584# Creating a front-end
5685
5786Text.Pandoc.App