@@ -91,7 +91,6 @@ Let's look at the types of `readMarkdown` and `writeRST`:
9191
9292```haskell
9393readMarkdown :: PandocMonad m => ReaderOptions -> Text -> m Pandoc
94−
9594writeRST :: PandocMonad m => WriterOptions -> Pandoc -> m Text
9695```
9796
@@ -125,12 +124,10 @@ setVerbosity :: PandocMonad m => Verbosity -> m ()
125124getLog :: PandocMonad m => m [LogMessage]
126125getLog = reverse <$> getsCommonState stLog
127126
128−-- | Log a message using 'logOutput'. Note that
129−-- 'logOutput' is called only if the verbosity
130−-- level exceeds the level of the message, but
131−-- the message is added to the list of log messages
132−-- that will be retrieved by 'getLog' regardless
133−-- of its verbosity level.
127+-- | Log a message using 'logOutput'. Note that 'logOutput' is
128+-- called only if the verbosity level exceeds the level of the
129+-- message, but the message is added to the list of log messages
130+-- that will be retrieved by 'getLog' regardless of its verbosity level.
134131report :: PandocMonad m => LogMessage -> m ()
135132
136133-- | Fetch an image or other item from the local filesystem or the net.
@@ -139,6 +136,7 @@ fetchItem :: PandocMonad m
139136 => String
140137 -> m (B.ByteString, Maybe MimeType)
141138
139+-- Set the resource path searched by 'fetchItem'.
142140setResourcePath :: PandocMonad m => [FilePath] -> m ()
143141```
144142
@@ -208,7 +206,7 @@ main :: IO ()
208206main = print mydoc
209207```
210208
211−If you use the `{-# LANGUAGE OverloadedStrings #-}`, you can
209+If you use the `OverloadedStrings` pragma, you can
212210simplify this further:
213211
214212```haskell
@@ -317,7 +315,12 @@ this behavior, use `setUserDataDir Nothing`.
317315
318316To render a template, use `renderTemplate'`, which takes two
319317arguments, a template (String) and a context (any instance
320−of ToJSON).
318+of ToJSON). If you want to create a context from the metadata
319+part of a Pandoc document, use `metaToJSON'` from
320+[Text.Pandoc.Writers.Shared]. If you also want to incorporate
321+values from variables, use `metaToJSON` instead, and make sure
322+`writerVariables` is set in `WriterOptions`.
323+
321324
322325# Handling errors and warnings
323326
@@ -415,22 +418,36 @@ listURLs = query urls
415418 urls _ = []
416419```
417420
418−# Creating a PDF
421+# Creating a front-end
422+
423+All of the functionality of the command-line program `pandoc`
424+has been abstracted out in `convertWithOpts` in
425+the module [Text.Pandoc.App]. Creating a GUI front-end for
426+pandoc is thus just a matter of populating the `Opts`
427+structure and calling this function.
419428
420−Text.Pandoc.PDF
421−makePDF (and note relevant parts of WriterOptions,
422−writerPdfArgs)
423−Actually: why not add writePdfEngine instead of having
424−this as a parameter? Or, make both parameters of makePDF.
425−Present hybrid makes no sense.
426−Should pdfengine be an enumerated type?
429+# Notes on using pandoc in web applications
427430
428−# Creating a front-end
431+1. Pandoc's parsers can exhibit pathological behavior on some
432+ inputs. So it is always a good idea to wrap uses of pandoc
433+ in a timeout function (e.g. `System.Timeout.timeout` from `base`)
434+ to prevent DOS attacks.
435+
436+2. If pandoc generates HTML from untrusted user input, it is
437+ always a good idea to filter the generated HTML through
438+ a sanitizer (such as `xss-sanitize`) to avoid security
439+ problems.
429440
430−to write a gui front end:
431−Text.Pandoc.App
441+3. Using `runPure` rather than `runIO` will ensure that
442+ pandoc's functions perform no IO operations (e.g. writing
443+ files). If some resources need to be made available, a
444+ "fake environment" is provided inside the state available
445+ to `runPure` (see `PureState` and its associated functions
446+ in [Text.Pandoc.Class]). It is also possible to write
447+ a custom instance of `PandocMonad` that, for example,
448+ makes wiki resources available as files in the fake environment,
449+ while isolating pandoc from the rest of the system.
432450
433−TODO: pandoc-servant?
434451
435452[Text.Pandoc.Definition]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
436453[Text.Pandoc.Walk]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html
@@ -440,4 +457,6 @@ TODO: pandoc-servant?
440457[Text.Pandoc.Builder]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
441458[Text.Pandoc.Templates]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Templates.html
442459[Text.Pandoc.Logging]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Logging.html
460+[Text.Pandoc.App]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-App.html
443461[Text.Pandoc.Error]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Error.html
462+[Text.Pandoc.Writers.Shared]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Writers.Shared.html