4cc2153 · typeable/pandoc

git.iko.soy/typeable/pandoc

on master help sign in

Finshed API guide. Closes #3289.

4cc2153John MacFarlane9 years ago

doc/using-the-pandoc-api.md+40−21

compare with master

unifiedsplit

@@ -91,7 +91,6 @@ Let's look at the types of `readMarkdown` and `writeRST`:

92```haskell

93readMarkdown :: PandocMonad m => ReaderOptions -> Text -> m Pandoc

94−

95writeRST :: PandocMonad m => WriterOptions -> Pandoc -> m Text

94writeRST :: PandocMonad m => WriterOptions -> Pandoc -> m Text

96```

95```

@@ -125,12 +124,10 @@ setVerbosity :: PandocMonad m => Verbosity -> m ()

125getLog :: PandocMonad m => m [LogMessage]

124getLog :: PandocMonad m => m [LogMessage]

126getLog = reverse <$> getsCommonState stLog

125getLog = reverse <$> getsCommonState stLog

127

126

128−-- | Log a message using 'logOutput'. Note that

127+-- | Log a message using 'logOutput'. Note that 'logOutput' is

129−-- 'logOutput' is called only if the verbosity

130−-- level exceeds the level of the message, but

128+-- called only if the verbosity level exceeds the level of the

131−-- the message is added to the list of log messages

129+-- message, but the message is added to the list of log messages

132−-- that will be retrieved by 'getLog' regardless

130+-- that will be retrieved by 'getLog' regardless of its verbosity level.

133−-- of its verbosity level.

134report :: PandocMonad m => LogMessage -> m ()

131report :: PandocMonad m => LogMessage -> m ()

135

132

136-- | Fetch an image or other item from the local filesystem or the net.

133-- | Fetch an image or other item from the local filesystem or the net.

@@ -139,6 +136,7 @@ fetchItem :: PandocMonad m

139 => String

136 => String

140 -> m (B.ByteString, Maybe MimeType)

137 -> m (B.ByteString, Maybe MimeType)

141

138

139+-- Set the resource path searched by 'fetchItem'.

142setResourcePath :: PandocMonad m => [FilePath] -> m ()

140setResourcePath :: PandocMonad m => [FilePath] -> m ()

143```

141```

144

142

@@ -208,7 +206,7 @@ main :: IO ()

208main = print mydoc

206main = print mydoc

209```

207```

210

208

211−If you use the `{-# LANGUAGE OverloadedStrings #-}`, you can

209+If you use the `OverloadedStrings` pragma, you can

212simplify this further:

210simplify this further:

213

211

214```haskell

212```haskell

@@ -317,7 +315,12 @@ this behavior, use `setUserDataDir Nothing`.

317

315

318To render a template, use `renderTemplate'`, which takes two

316To render a template, use `renderTemplate'`, which takes two

319arguments, a template (String) and a context (any instance

317arguments, 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+

321

324

322# Handling errors and warnings

325# Handling errors and warnings

323

326

@@ -415,22 +418,36 @@ listURLs = query urls

415 urls _ = []

418 urls _ = []

416```

419```

417

420

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.

419

428

420−Text.Pandoc.PDF

429+# Notes on using pandoc in web applications

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?

427

430

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.

429

440

430−to write a gui front end:

441+3. Using `runPure` rather than `runIO` will ensure that

431−Text.Pandoc.App

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.

432

450

433−TODO: pandoc-servant?

434

451

435[Text.Pandoc.Definition]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html

452[Text.Pandoc.Definition]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html

436[Text.Pandoc.Walk]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html

453[Text.Pandoc.Walk]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html

@@ -440,4 +457,6 @@ TODO: pandoc-servant?

440[Text.Pandoc.Builder]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html

457[Text.Pandoc.Builder]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html

441[Text.Pandoc.Templates]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Templates.html

458[Text.Pandoc.Templates]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Templates.html

442[Text.Pandoc.Logging]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Logging.html

459[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

443[Text.Pandoc.Error]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Error.html

461[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