@@ -188,20 +188,40 @@ Some particularly important options to know about:
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`.
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:
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
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 ".")
198−Example.
207+main :: IO ()
199−Here’s a JSON data source about CNG fueling stations in the
208+main = print mydoc
200−Chicago area: cng_fuel_chicago.json. Boss says: write me a
209+```
201−letter in Word listing all the stations that take the Voyager
211+If you use the `{-# LANGUAGE OverloadedStrings #-}`, you can
212+simplify this further:
215+mydoc = doc $ header 1 "Hello!"
216+ <> para (emph "hello world" <> ".")
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`):
206 "state" : "IL",
226 "state" : "IL",
207 "city" : "Chicago",
227 "city" : "Chicago",
@@ -213,9 +233,10 @@ card.
216−No need to open Word for this job! fuel.hs
236+And then use aeson and pandoc to parse the JSON and create
219{-# LANGUAGE OverloadedStrings #-}
240{-# LANGUAGE OverloadedStrings #-}
220import Text.Pandoc.Builder
241import Text.Pandoc.Builder
221import Text.Pandoc
242import Text.Pandoc
@@ -252,31 +273,43 @@ createLetter stations = doc $
252 stationToRow station =
273 stationToRow station =
253 [ plain (text $ name station)
274 [ plain (text $ name station)
254 , plain (text $ address station)
275 , plain (text $ address station)
255− , plain (mconcat $ intersperse linebreak $ map text $ cardsAccepted station)
276+ , plain (mconcat $ intersperse linebreak
277+ $ map text $ cardsAccepted station)
258main :: IO ()
280main :: IO ()
260− json <- BL.readFile "cng_fuel_chicago.json"
282+ json <- BL.readFile "fuel.json"
261 let letter = case decode json of
283 let letter = case decode json of
262 Just stations -> createLetter [s | s <- stations,
284 Just stations -> createLetter [s | s <- stations,
263 "Voyager" `elem` cardsAccepted s]
285 "Voyager" `elem` cardsAccepted s]
264 Nothing -> error "Could not decode JSON"
286 Nothing -> error "Could not decode JSON"
287+ docx <- runIO (writeDocx def letter) >>= handleError
265− BL.writeFile "letter.docx" =<< writeDocx def letter
288+ BL.writeFile "letter.docx" docx
266 putStrLn "Created letter.docx"
289 putStrLn "Created letter.docx"
269−
292+Voila! You've written the letter without using Word and
293+without looking at the data.
271# Templates and other data files
295# Templates and other data files
273readDataFile
297readDataFile
275# Handling errors and warnings
301# Handling errors and warnings
277−# Generic transformations
303+Text.Pandoc.Error
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)
@@ -284,8 +317,9 @@ Filters: see filters.md
285applyFilters, applyLuaFilters from Text.Pandoc.App.
318applyFilters, applyLuaFilters from Text.Pandoc.App.
287−# PDF
320+# Creating a PDF
290# Creating a front-end
324# Creating a front-end