@@ -188,20 +188,40 @@ Some particularly important options to know about:
188188
189189# Builder
190190
191+Sometimes it's useful to construct a Pandoc document
192+programatically. 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`.
191194
192−Inlines vs Inline, etc.
195+Because concatenating lists is slow, we use special
196+types `Inlines` and `Blocks` that wrap a `Sequence` of
197+`Inline` and `Block` elements. These are instances
198+of the Monoid typeclass and can easily be concatenated:
193199
194−Concatenating lists is slow. So we use special types Inlines and Blocks that wrap Sequences of Inline and Block elements.
200+```haskell
201+import Text.Pandoc.Builder
195202
196−Monoid - makes it easy to build up docs programatically.
203+mydoc :: Pandoc
204+mydoc = doc $ header 1 (text "Hello!")
205+ <> para (emph (text "hello world") <> text ".")
197206
198−Example.
199−Here’s a JSON data source about CNG fueling stations in the
200−Chicago area: cng_fuel_chicago.json. Boss says: write me a
201−letter in Word listing all the stations that take the Voyager
202−card.
207+main :: IO ()
208+main = print mydoc
209+```
203210
211+If you use the `{-# LANGUAGE OverloadedStrings #-}`, you can
212+simplify this further:
213+
214+```haskell
215+mydoc = doc $ header 1 "Hello!"
216+ <> para (emph "hello world" <> ".")
204217```
218+
219+Here's a more realistic example. Suppose your boss says: write
220+me a letter in Word listing all the filling stations in Chicago
221+that take the Voyager card. You find some JSON data in this
222+format (`fuel.json`):
223+
224+```json
205225[ {
206226 "state" : "IL",
207227 "city" : "Chicago",
@@ -213,9 +233,10 @@ card.
213233}, ...
214234```
215235
216−No need to open Word for this job! fuel.hs
236+And then use aeson and pandoc to parse the JSON and create
237+the Word document:
217238
218−```
239+```haskell
219240{-# LANGUAGE OverloadedStrings #-}
220241import Text.Pandoc.Builder
221242import Text.Pandoc
@@ -252,31 +273,43 @@ createLetter stations = doc $
252273 stationToRow station =
253274 [ plain (text $ name station)
254275 , plain (text $ address station)
255− , plain (mconcat $ intersperse linebreak $ map text $ cardsAccepted station)
276+ , plain (mconcat $ intersperse linebreak
277+ $ map text $ cardsAccepted station)
256278 ]
257279
258280main :: IO ()
259281main = do
260− json <- BL.readFile "cng_fuel_chicago.json"
282+ json <- BL.readFile "fuel.json"
261283 let letter = case decode json of
262284 Just stations -> createLetter [s | s <- stations,
263285 "Voyager" `elem` cardsAccepted s]
264286 Nothing -> error "Could not decode JSON"
265− BL.writeFile "letter.docx" =<< writeDocx def letter
287+ docx <- runIO (writeDocx def letter) >>= handleError
288+ BL.writeFile "letter.docx" docx
266289 putStrLn "Created letter.docx"
267290```
268291
269−
292+Voila! You've written the letter without using Word and
293+without looking at the data.
270294
271295# Templates and other data files
272296
273297readDataFile
274298
299+getTemplate
300+
275301# Handling errors and warnings
276302
277−# Generic transformations
303+Text.Pandoc.Error
304+Text.Pandoc.Logging
305+getLog
306+verbosity
307+
308+# Walking the AST
278309
279−Walk and syb for AST transformations
310+Text.Pandoc.Walk for AST transformations
311+walk and query, with examples
312+(don't bother mentioning syb)
280313
281314# Filters
282315
@@ -284,8 +317,9 @@ Filters: see filters.md
284317
285318applyFilters, applyLuaFilters from Text.Pandoc.App.
286319
287−# PDF
320+# Creating a PDF
288321
322+Text.Pandoc.PDF
289323
290324# Creating a front-end
291325