d4f48e7 · typeable/pandoc

git.iko.soy/typeable/pandoc

on master help sign in

Added abc.lua example to lua-filters documentation.

d4f48e7John MacFarlane9 years ago

doc/lua-filters.md+61−14

compare with master

unifiedsplit

@@ -36,7 +36,7 @@ JSON to stdout and reading it from stdin.

36Here is an example of a lua filter that converts strong emphasis

37to small caps:

39−``` {.lua}

39+``` lua

40return {

41 {

42 Strong = function (elem)

@@ -48,7 +48,7 @@ return {

49or equivalently,

51−``` {.lua}

51+``` lua

52function Strong(elem)

53 return pandoc.SmallCaps(elem.c)

54end

@@ -163,10 +163,15 @@ those elements accessible through the filter function parameter.

163

164## Exposed pandoc functionality

165

166−Some filters will require access to certain functions provided

166+Some pandoc functions have been made available in lua:

167−by pandoc. This is currently limited to the `read` function

167+

168−which allows to parse strings into pandoc documents from within

168+- `read` allows filters to parse strings into pandoc documents

169−the lua filter.

169+- `pipe` runs an external command with input from and output to

170+ strings

171+- `sha1` generates a SHA1 hash

172+- The `mediabag` module allows access to the "mediabag,"

173+ which stores binary content such as images that may be

174+ included in the final document.

170

175

171# Examples

176# Examples

172

177

@@ -175,7 +180,7 @@ the lua filter.

175The following filter converts the string `{{helloworld}}` into

180The following filter converts the string `{{helloworld}}` into

176emphasized text "Hello, World".

181emphasized text "Hello, World".

177

182

178−``` {.lua}

183+``` lua

179return {

184return {

180 {

185 {

181 Str = function (elem)

186 Str = function (elem)

@@ -195,7 +200,7 @@ This filter causes metadata defined in an external file

195(`metadata-file.yaml`) to be used as default values in a

200(`metadata-file.yaml`) to be used as default values in a

196document's metadata:

201document's metadata:

197

202

198−``` {.lua}

203+``` lua

199-- read metadata file into string

204-- read metadata file into string

200local metafile = io.open('metadata-file.yaml', 'r')

205local metafile = io.open('metadata-file.yaml', 'r')

201local content = metafile:read("*a")

206local content = metafile:read("*a")

@@ -222,7 +227,7 @@ return {

222This filter sets the date in the document's metadata to the

227This filter sets the date in the document's metadata to the

223current date:

228current date:

224

229

225−``` {.lua}

230+``` lua

226function Meta(m)

231function Meta(m)

227 m.date = os.date("%B %e, %Y")

232 m.date = os.date("%B %e, %Y")

228 return m

233 return m

@@ -234,7 +239,7 @@ end

234This filter prints a table of all the URLs linked to in the

239This filter prints a table of all the URLs linked to in the

235document, together with the number of links to that URL.

240document, together with the number of links to that URL.

236

241

237−``` {.lua}

242+``` lua

238links = {}

243links = {}

239

244

240function Link (el)

245function Link (el)

@@ -275,7 +280,7 @@ Passing information from a higher level (e.g., metadata) to a

275lower level (e.g., inlines) is still possible by using two

280lower level (e.g., inlines) is still possible by using two

276filters living in the same file:

281filters living in the same file:

277

282

278−``` {.lua}

283+``` lua

279local vars = {}

284local vars = {}

280

285

281function get_vars (meta)

286function get_vars (meta)

@@ -328,6 +333,49 @@ will output:

328</dl>

333</dl>

329```

334```

330

335

336+## Converting ABC code to music notation

337+

338+This filter replaces code blocks with class `abc` with

339+images created by running their contents through `abcm2ps`

340+and ImageMagick's `convert`. (For more on ABC notation, see

341+<http://abcnotation.com>.)

342+

343+Images are added to the mediabag. For output to binary

344+formats, pandoc will use images in the mediabag. For textual

345+formats, use `--extract-media` to specify a directory where

346+the files in the mediabag will be written, or (for HTML only)

347+use `--self-contained`.

348+

349+``` lua

350+-- Pandoc filter to process code blocks with class "abc" containing

351+-- ABC notation into images.

352+--

353+-- * Assumes that abcm2ps and ImageMagick's convert are in the path.

354+-- * For textual output formats, use --extract-media=abc-images

355+-- * For HTML formats, you may alternatively use --self-contained

356+

357+local filetypes = { html = {"png", "image/png"}

358+ , latex = {"pdf", "application/pdf"}

359+ }

360+local filetype = filetypes[FORMAT][1] or "png"

361+local mimetype = filetypes[FORMAT][2] or "image/png"

362+

363+local function abc2eps(abc, filetype)

364+ local eps = pandoc.pipe("abcm2ps", {"-q", "-O", "-", "-"}, abc)

365+ local final = pandoc.pipe("convert", {"-", filetype .. ":-"}, eps)

366+ return final

367+end

368+

369+function CodeBlock(block)

370+ if block.classes[1] == "abc" then

371+ local img = abc2eps(block.text, filetype)

372+ local fname = pandoc.sha1(img) .. "." .. filetype

373+ pandoc.mediabag.insert(fname, mimetype, img)

374+ return pandoc.Para{ pandoc.Image({pandoc.Str("abc tune")}, fname) }

375+ end

376+end

377+```

378+

331# Module pandoc

379# Module pandoc

332

380

333Lua functions for pandoc scripts.

381Lua functions for pandoc scripts.

@@ -1078,16 +1126,15 @@ Lua functions for pandoc scripts.

1078[`pipe (command, args, input)`]{#mediabag-sha1}

1126[`pipe (command, args, input)`]{#mediabag-sha1}

1079

1127

1080: Runs command with arguments, passing it some input,

1128: Runs command with arguments, passing it some input,

1081− and returns the exit code and the output.

1129+ and returns the output.

1082

1130

1083 Returns:

1131 Returns:

1084

1132

1085− - Exit code from command.

1086 - Output of command.

1133 - Output of command.

1087

1134

1088 Usage:

1135 Usage:

1089

1136

1090− local ec, output = pandoc.pipe("sed", {"-e","s/a/b/"}, "abc")

1137+ local output = pandoc.pipe("sed", {"-e","s/a/b/"}, "abc")

1091

1138

1092

1139

1093# Submodule mediabag

1140# Submodule mediabag