@@ -27,21 +27,19 @@ conversions with $M$ readers and $N$ writers.
2727The Pandoc AST is defined in the
2828[pandoc-types](https://hackage.haskell.org/package/pandoc-types)
2929package. You should start by looking at the Haddock
30−documentation for
31−[Text.Pandoc.Definition](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). As you'll see, a `Pandoc` is
32−composed of some metadata and a list of `Block`s. There are
33−various kinds of `Block`, including `Para` (paragraph),
34−`Header` (section heading), and `BlockQuote`. Some of the
35−`Block`s (like `BlockQuote`) contain lists of `Block`s,
36−while others (like `Para`) contain lists of `Inline`s, and
37−still others (like `CodeBlock`) contain plain text or
38−nothing. `Inline`s are the basic elements of paragraphs.
39−The distinction between `Block` and `Inline` in the type
40−system makes it impossible to represent, for example,
41−a link (`Inline`) whose link text is a block quote (`Block`).
42−This expressive limitation is mostly a help rather than a
43−hindrance, since many of the formats pandoc supports have
44−similar limitations.
30+documentation for [Text.Pandoc.Definition]. As you'll see, a
31+`Pandoc` is composed of some metadata and a list of `Block`s.
32+There are various kinds of `Block`, including `Para`
33+(paragraph), `Header` (section heading), and `BlockQuote`. Some
34+of the `Block`s (like `BlockQuote`) contain lists of `Block`s,
35+while others (like `Para`) contain lists of `Inline`s, and still
36+others (like `CodeBlock`) contain plain text or nothing.
37+`Inline`s are the basic elements of paragraphs. The distinction
38+between `Block` and `Inline` in the type system makes it
39+impossible to represent, for example, a link (`Inline`) whose
40+link text is a block quote (`Block`). This expressive
41+limitation is mostly a help rather than a hindrance, since many
42+of the formats pandoc supports have similar limitations.
4543
4644The best way to explore the pandoc AST is to use `pandoc -t
4745native`, which will display the AST correspoding to some
@@ -101,7 +99,7 @@ The `PandocMonad m =>` part is a typeclass constraint.
10199It says that `readMarkdown` and `writeRST` define computations
102100that can be used in any instance of the `PandocMonad`
103101type class. `PandocMonad` is defined in the module
104−Text.Pandoc.Class.
102+[Text.Pandoc.Class].
105103
106104Two instances of `PandocMonad` are provided: `PandocIO` and
107105`PandocPure`. The difference is that computations run in
@@ -112,8 +110,7 @@ to prevent users from doing anything malicious. To run the
112110conversion in `PandocIO`, use `runIO` (as above). To run it in
113111`PandocPure`, use `runPure`.
114112
115−As you can see from the Haddocks,
116−[Text.Pandoc.Class](https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Class.html)
113+As you can see from the Haddocks, [Text.Pandoc.Class]
117114exports many auxiliary functions that can be used in any
118115instance of `PandocMonad`. For example:
119116
@@ -156,14 +153,17 @@ section, we could do this:
156153 writeRST def doc
157154```
158155
156+Note that `PandocIO` is an instance of `MonadIO`, so you can
157+use `liftIO` to perform arbitrary IO operations inside a pandoc
158+conversion chain.
159+
159160# Options
160161
161162The first argument of each reader or writer is for
162163options controlling the behavior of the reader or writer:
163164`ReaderOptions` for readers and `WriterOptions`
164−for writers. These are defined in
165−[Text.Pandoc.Options](https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Options.html). It is a good idea to study these
166−options to see what can be adjusted.
165+for writers. These are defined in [Text.Pandoc.Options]. It is
166+a good idea to study these options to see what can be adjusted.
167167
168168`def` (from Data.Default) denotes a default value for
169169each kind of option. (You can also use `defaultWriterOptions`
@@ -184,13 +184,13 @@ Some particularly important options to know about:
184184
1851852. `readerExtensions` and `writerExtensions`: These specify
186186 the extensions to be used in parsing and rendering.
187− Extensions are defined in [Text.Pandoc.Extensions](https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Extensions.html).
187+ Extensions are defined in [Text.Pandoc.Extensions].
188188
189189# Builder
190190
191191Sometimes it's useful to construct a Pandoc document
192192programatically. To make this easier we provide the
193−module [Text.Pandoc.Builder](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html) in `pandoc-types`.
193+module [Text.Pandoc.Builder] `pandoc-types`.
194194
195195Because concatenating lists is slow, we use special
196196types `Inlines` and `Blocks` that wrap a `Sequence` of
@@ -292,36 +292,99 @@ main = do
292292Voila! You've written the letter without using Word and
293293without looking at the data.
294294
295−# Templates and other data files
296−
297−readDataFile
298−
299−getTemplate
295+# Data files
296+
297+Pandoc has a number of data files, which can be found in the
298+`data/` subdirectory of the repository. These are installed
299+with pandoc (or, if pandoc was compiled with the
300+`embed_data_files` flag, they are embedded in the binary).
301+You can retrieve data files using `readDataFile` from
302+Text.Pandoc.Class. `readDataFile` will first look for the
303+file in the "user data directory" (`setUserDataDir`,
304+`getUserDataDir`), and if it is not found there, it will
305+return the default installed with the system.
306+To force the use of the default, `setUserDataDir Nothing`.
307+
308+# Templates
309+
310+Pandoc has its own template system, described in the User's
311+Guide. To retrieve the default template for a system,
312+use `getDefaultTemplate` from [Text.Pandoc.Templates].
313+Note that this looks first in the
314+`templates` subdirectory of the user data directory, allowing
315+users to override the system defaults. If you want to disable
316+this behavior, use `setUserDataDir Nothing`.
317+
318+To render a template, use `renderTemplate'`, which takes two
319+arguments, a template (String) and a context (any instance
320+of ToJSON).
300321
301322# Handling errors and warnings
302323
303−Text.Pandoc.Error
304−Text.Pandoc.Logging
305−getLog
306−verbosity
324+`runIO` and `runPure` return an `Either PandocError a`. All errors
325+raised in running a `PandocMonad` computation will be trapped
326+and returned as a `Left` value, so they can be handled by
327+the calling program. To see the constructors for `PandocError`,
328+see the documentation for [Text.Pandoc.Error].
329+
330+To raise a `PandocError` from inside a `PandocMonad` computation,
331+use `throwError`.
332+
333+In addition to errors, which stop execution of the conversion
334+pipeline, one can generate informational messages.
335+Use `report` from [Text.Pandoc.Class] to issue a `LogMessage`.
336+For a list of cosntructors for `LogMessage`, see
337+[Text.Pandoc.Logging]. Note that each type of log message
338+is associated with a verbosity level. The verbosity level
339+(`setVerbosity`/`getVerbosity`) determines whether the report
340+will be printed to stderr (when running in `PandocIO`), but
341+regardless of verbosity level, all reported messages are stored
342+internally and may be retrieved using `getLog`.
307343
308344# Walking the AST
309345
310−Text.Pandoc.Walk for AST transformations
346+It is often useful to walk the Pandoc AST either to extract
347+information (e.g., what are all the URLs linked to in this
348+document?, do all the code samples compile?) or to transform a
349+document (e.g., increase the level of every section header,
350+remove emphasis, or replace specially marked code blocks with
351+images). To make this easier and more efficient, `pandoc-types`
352+includes a module [Text.Pandoc.Walk].
353+
311354walk and query, with examples
312−(don't bother mentioning syb)
355+including RawBlock
313356
314357# Filters
315358
316−Filters: see filters.md
359+These make it easy for users to add their own transformations.
360+two types: json and lua.
361+Filters: see filters.md, lua-filters.md
317362
318363applyFilters, applyLuaFilters from Text.Pandoc.App.
319364
320365# Creating a PDF
321366
322367Text.Pandoc.PDF
368+makePDF (and note relevant parts of WriterOptions,
369+writerPdfArgs)
370+Actually: why not add writePdfEngine instead of having
371+this as a parameter? Or, make both parameters of makePDF.
372+Present hybrid makes no sense.
373+Should pdfengine be an enumerated type?
323374
324375# Creating a front-end
325376
377+to write a gui front end:
326378Text.Pandoc.App
327379
380+TODO: pandoc-servant?
381+
382+[Text.Pandoc.Definition]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
383+[Text.Pandoc.Walk]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html
384+[Text.Pandoc.Class]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Class.html
385+[Text.Pandoc.Options]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Options.html
386+[Text.Pandoc.Extensions]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Extensions.html
387+[Text.Pandoc.Builder]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
388+[Text.Pandoc.Templates]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Templates.html
389+[Text.Pandoc.Logging]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Logging.html
390+[Text.Pandoc.Error]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Error.html