@@ -27,21 +27,19 @@ conversions with $M$ readers and $N$ writers.
27The Pandoc AST is defined in the
27The Pandoc AST is defined in the
28[pandoc-types](https://hackage.haskell.org/package/pandoc-types)
28[pandoc-types](https://hackage.haskell.org/package/pandoc-types)
29package. You should start by looking at the Haddock
29package. You should start by looking at the Haddock
30−documentation for
30+documentation for [Text.Pandoc.Definition]. As you'll see, a
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
31+`Pandoc` is composed of some metadata and a list of `Block`s.
33−various kinds of `Block`, including `Para` (paragraph),
32+There are various kinds of `Block`, including `Para`
34−`Header` (section heading), and `BlockQuote`. Some of the
33+(paragraph), `Header` (section heading), and `BlockQuote`. Some
35−`Block`s (like `BlockQuote`) contain lists of `Block`s,
34+of the `Block`s (like `BlockQuote`) contain lists of `Block`s,
36−while others (like `Para`) contain lists of `Inline`s, and
35+while others (like `Para`) contain lists of `Inline`s, and still
37−still others (like `CodeBlock`) contain plain text or
36+others (like `CodeBlock`) contain plain text or nothing.
38−nothing. `Inline`s are the basic elements of paragraphs.
37+`Inline`s are the basic elements of paragraphs. The distinction
39−The distinction between `Block` and `Inline` in the type
38+between `Block` and `Inline` in the type system makes it
40−system makes it impossible to represent, for example,
39+impossible to represent, for example, a link (`Inline`) whose
41−a link (`Inline`) whose link text is a block quote (`Block`).
40+link text is a block quote (`Block`). This expressive
42−This expressive limitation is mostly a help rather than a
41+limitation is mostly a help rather than a hindrance, since many
43−hindrance, since many of the formats pandoc supports have
42+of the formats pandoc supports have similar limitations.
46The best way to explore the pandoc AST is to use `pandoc -t
44The best way to explore the pandoc AST is to use `pandoc -t
47native`, which will display the AST correspoding to some
45native`, which will display the AST correspoding to some
@@ -101,7 +99,7 @@ The `PandocMonad m =>` part is a typeclass constraint.
101It says that `readMarkdown` and `writeRST` define computations
99It says that `readMarkdown` and `writeRST` define computations
102that can be used in any instance of the `PandocMonad`
100that can be used in any instance of the `PandocMonad`
103type class. `PandocMonad` is defined in the module
101type class. `PandocMonad` is defined in the module
104−Text.Pandoc.Class.
102+[Text.Pandoc.Class].
106Two instances of `PandocMonad` are provided: `PandocIO` and
104Two instances of `PandocMonad` are provided: `PandocIO` and
107`PandocPure`. The difference is that computations run in
105`PandocPure`. The difference is that computations run in
@@ -112,8 +110,7 @@ to prevent users from doing anything malicious. To run the
112conversion in `PandocIO`, use `runIO` (as above). To run it in
110conversion in `PandocIO`, use `runIO` (as above). To run it in
113`PandocPure`, use `runPure`.
111`PandocPure`, use `runPure`.
115−As you can see from the Haddocks,
113+As you can see from the Haddocks, [Text.Pandoc.Class]
116−[Text.Pandoc.Class](https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Class.html)
117exports many auxiliary functions that can be used in any
114exports many auxiliary functions that can be used in any
118instance of `PandocMonad`. For example:
115instance of `PandocMonad`. For example:
@@ -156,14 +153,17 @@ section, we could do this:
156 writeRST def doc
153 writeRST def doc
156+Note that `PandocIO` is an instance of `MonadIO`, so you can
157+use `liftIO` to perform arbitrary IO operations inside a pandoc
161The first argument of each reader or writer is for
162The first argument of each reader or writer is for
162options controlling the behavior of the reader or writer:
163options controlling the behavior of the reader or writer:
163`ReaderOptions` for readers and `WriterOptions`
164`ReaderOptions` for readers and `WriterOptions`
164−for writers. These are defined in
165+for writers. These are defined in [Text.Pandoc.Options]. It is
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.
166+a good idea to study these options to see what can be adjusted.
168`def` (from Data.Default) denotes a default value for
168`def` (from Data.Default) denotes a default value for
169each kind of option. (You can also use `defaultWriterOptions`
169each kind of option. (You can also use `defaultWriterOptions`
@@ -184,13 +184,13 @@ Some particularly important options to know about:
1852. `readerExtensions` and `writerExtensions`: These specify
1852. `readerExtensions` and `writerExtensions`: These specify
186 the extensions to be used in parsing and rendering.
186 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].
191Sometimes it's useful to construct a Pandoc document
191Sometimes it's useful to construct a Pandoc document
192programatically. To make this easier we provide the
192programatically. 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`.
195Because concatenating lists is slow, we use special
195Because concatenating lists is slow, we use special
196types `Inlines` and `Blocks` that wrap a `Sequence` of
196types `Inlines` and `Blocks` that wrap a `Sequence` of
@@ -292,36 +292,99 @@ main = do
292Voila! You've written the letter without using Word and
292Voila! You've written the letter without using Word and
293without looking at the data.
293without looking at the data.
295−# Templates and other data files
295+# Data files
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).
297−readDataFile
301+You can retrieve data files using `readDataFile` from
298−
302+Text.Pandoc.Class. `readDataFile` will first look for the
299−getTemplate
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`.
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`.
318+To render a template, use `renderTemplate'`, which takes two
319+arguments, a template (String) and a context (any instance
301# Handling errors and warnings
322# Handling errors and warnings
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`,
303−Text.Pandoc.Error
328+see the documentation for [Text.Pandoc.Error].
330+To raise a `PandocError` from inside a `PandocMonad` computation,
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
304−Text.Pandoc.Logging
337+[Text.Pandoc.Logging]. Note that each type of log message
305−getLog
338+is associated with a verbosity level. The verbosity level
306−verbosity
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`.
308# Walking the AST
344# Walking the AST
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`
310−Text.Pandoc.Walk for AST transformations
352+includes a module [Text.Pandoc.Walk].
311walk and query, with examples
354walk and query, with examples
312−(don't bother mentioning syb)
355+including RawBlock
359+These make it easy for users to add their own transformations.
360+two types: json and lua.
316−Filters: see filters.md
361+Filters: see filters.md, lua-filters.md
318applyFilters, applyLuaFilters from Text.Pandoc.App.
363applyFilters, applyLuaFilters from Text.Pandoc.App.
320# Creating a PDF
365# Creating a PDF
322Text.Pandoc.PDF
367Text.Pandoc.PDF
368+makePDF (and note relevant parts of WriterOptions,
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?
324# Creating a front-end
375# Creating a front-end
377+to write a gui front end:
326Text.Pandoc.App
378Text.Pandoc.App
380+TODO: pandoc-servant?
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