c602ed3 · typeable/pandoc

git.iko.soy/typeable/pandoc

on master help sign in

Added and documented --template option.

c602ed3fiddlosopher17 years ago

README+71

compare with master

unifiedsplit

@@ -282,6 +282,13 @@ For further documentation, see the `pandoc(1)` man page.

282 one) in the output document. This option has no effect with `man`,

283 `docbook`, or `s5` output formats.

284

285+`--template=`*file*

286+: uses *file* as a custom template for the generated document. Implies

287+ `-s`. See [Templates](#templates) below for a description

288+ of template syntax. If this option is not used, a default

289+ template appropriate for the output format will be used. See also

290+ `-D/--print-default-template`.

291+

285`-c` or `--css` *filename*

292`-c` or `--css` *filename*

286: allows the user to specify a custom stylesheet that will be linked to

293: allows the user to specify a custom stylesheet that will be linked to

287 in HTML and S5 output. This option can be used repeatedly to include

294 in HTML and S5 output. This option can be used repeatedly to include

@@ -437,6 +444,70 @@ For further documentation, see the `pandoc(1)` man page.

437[gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html

444[gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html

438[mimeTeX]: http://www.forkosh.com/mimetex.html

445[mimeTeX]: http://www.forkosh.com/mimetex.html

439

446

447+Templates

448+=========

449+

450+When the `-s/--standalone` option is used, pandoc uses a template to

451+add header and footer material that is needed for a self-standing

452+document. To see the default template that is used, just type

453+

454+ pandoc --print-default-template=FORMAT

455+

456+where `FORMAT` is the name of the output format. A custom template

457+can be specified using the `--template` option.

458+

459+Templates may contain *variables*. Variable names are sequences of

460+alphanumerics, `-`, and `_`, starting with a letter. A variable name

461+surrounded by `$` signs will be replaced by its value. For example,

462+the string `$title$` in

463+

464+ <title>$title$</title>

465+

466+will be replaced by the document title.

467+

468+Some variables are set automatically by pandoc. These vary somewhat

469+depending on the output format, but include:

470+

471+`before`

472+: contents specified by `-B/--include-before-body`

473+`after`

474+: contents specified by `-A/--include-after-body`

475+`legacy-header`

476+: contents specified by `-C/--custom-header`

477+`header-includes`

478+: contents specified by `-H/--include-in-header`

479+`toc`

480+: non-null value if `--toc/--table-of-contents` was specified

481+`body`

482+: body of document

483+`title`

484+: title of document, as specified in title block

485+`authors`

486+: authors of document, as specified in title block

487+`date`

488+: date of document, as specified in title block

489+`css`

490+: links to CSS files, as specified using `-c/--css`

491+

492+Variables may be set at the command line using the

493+`--set` option. This allows users to include custom variables in

494+their templates.

495+

496+Templates may contain conditionals. The syntax is as follows:

497+

498+ $if(variable)$

499+ X

500+ $else$

501+ Y

502+ $endif$

503+

504+This will include `X` in the template if `variable` has a non-null

505+value; otherwise it will include `Y`. `X` and `Y` are placeholders for

506+any valid template text, and may include interpolated variables or other

507+conditionals. The `$else$` section may be omitted.

508+

509+To write a literal `$` in a template, use `$$`.

510+

440Pandoc's markdown vs. standard markdown

511Pandoc's markdown vs. standard markdown

441=======================================

512=======================================

442

513

man/man1/markdown2pdf.1.md+5

@@ -49,6 +49,11 @@ The following options are most relevant:

49-N, \--number-sections

50: Number section headings in LaTeX output. (Default is not to number them.)

52+\--template=*FILE*

53+: Use *FILE* as a custom template for the generated document. Implies

54+ `-s`. See the section TEMPLATES in `pandoc`(1) for information about

55+ template syntax.

56+

52-H *FILE*, \--include-in-header=*FILE*

57-H *FILE*, \--include-in-header=*FILE*

53: Include (LaTeX) contents of *FILE* at the end of the header. Implies

58: Include (LaTeX) contents of *FILE* at the end of the header. Implies

54 `-s`.

59 `-s`.

man/man1/pandoc.1.md+71−1

@@ -169,6 +169,12 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.

169 RTF) or an instruction to create one (LaTeX, reStructuredText).

170 This option has no effect on man, DocBook, or S5 output.

171

172+\--template=*FILE*

173+: Use *FILE* as a custom template for the generated document. Implies

174+ `-s`. See TEMPLATES below for a description of template syntax. If

175+ this option is not used, a default template appropriate for the

176+ output format will be used. See also `-D/--print-default-template`.

177+

172-c *CSS*, \--css=*CSS*

178-c *CSS*, \--css=*CSS*

173: Link to a CSS style sheet. *CSS* is the pathname of the style sheet.

179: Link to a CSS style sheet. *CSS* is the pathname of the style sheet.

174

180

@@ -184,7 +190,8 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.

184-C *FILE*, \--custom-header=*FILE*

190-C *FILE*, \--custom-header=*FILE*

185: Use contents of *FILE* as the document header (overriding the

191: Use contents of *FILE* as the document header (overriding the

186 default header, which can be printed by using the `-D` option).

192 default header, which can be printed by using the `-D` option).

187− Implies `-s`.

193+ Implies `-s`. Note: This option is deprecated. Users should

194+ transition to using `--template` instead.

188

195

189-D *FORMAT*, \--print-default-template=*FORMAT*

196-D *FORMAT*, \--print-default-template=*FORMAT*

190: Print the default template for an output *FORMAT*. (See `-t`

197: Print the default template for an output *FORMAT*. (See `-t`

@@ -219,6 +226,69 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.

219-h, \--help

226-h, \--help

220: Show usage message.

227: Show usage message.

221

228

229+# TEMPLATES

230+

231+When the `-s/--standalone` option is used, pandoc uses a template to

232+add header and footer material that is needed for a self-standing

233+document. To see the default template that is used, just type

234+

235+ pandoc --print-default-template=FORMAT

236+

237+where `FORMAT` is the name of the output format. A custom template

238+can be specified using the `--template` option.

239+

240+Templates may contain *variables*. Variable names are sequences of

241+alphanumerics, `-`, and `_`, starting with a letter. A variable name

242+surrounded by `$` signs will be replaced by its value. For example,

243+the string `$title$` in

244+

245+ <title>$title$</title>

246+

247+will be replaced by the document title.

248+

249+Some variables are set automatically by pandoc. These vary somewhat

250+depending on the output format, but include:

251+

252+`before`

253+: contents specified by `-B/--include-before-body`

254+`after`

255+: contents specified by `-A/--include-after-body`

256+`legacy-header`

257+: contents specified by `-C/--custom-header`

258+`header-includes`

259+: contents specified by `-H/--include-in-header`

260+`toc`

261+: non-null value if `--toc/--table-of-contents` was specified

262+`body`

263+: body of document

264+`title`

265+: title of document, as specified in title block

266+`authors`

267+: authors of document, as specified in title block

268+`date`

269+: date of document, as specified in title block

270+`css`

271+: links to CSS files, as specified using `-c/--css`

272+

273+Variables may be set at the command line using the

274+`--set` option. This allows users to include custom variables in

275+their templates.

276+

277+Templates may contain conditionals. The syntax is as follows:

278+

279+ $if(variable)$

280+ X

281+ $else$

282+ Y

283+ $endif$

284+

285+This will include `X` in the template if `variable` has a non-null

286+value; otherwise it will include `Y`. `X` and `Y` are placeholders for

287+any valid template text, and may include interpolated variables or other

288+conditionals. The `$else$` section may be omitted.

289+

290+To write a literal `$` in a template, use `$$`.

291+

222# SEE ALSO

292# SEE ALSO

223

293

224`hsmarkdown`(1),

294`hsmarkdown`(1),

src/pandoc.hs+16−2

@@ -135,6 +135,7 @@ data Opt = Opt

135 , optParseRaw :: Bool -- ^ Parse unconvertable HTML and TeX

136 , optCSS :: [String] -- ^ CSS file to link to

137 , optTableOfContents :: Bool -- ^ Include table of contents

138+ , optTemplate :: String -- ^ Custom template

138 , optVariables :: [(String,String)] -- ^ Template variables to set

139 , optVariables :: [(String,String)] -- ^ Template variables to set

139 , optIncludeInHeader :: String -- ^ File to include in header

140 , optIncludeInHeader :: String -- ^ File to include in header

140 , optIncludeBeforeBody :: String -- ^ File to include at top of body

141 , optIncludeBeforeBody :: String -- ^ File to include at top of body

@@ -173,6 +174,7 @@ defaultOpts = Opt

173 , optParseRaw = False

174 , optParseRaw = False

174 , optCSS = []

175 , optCSS = []

175 , optTableOfContents = False

176 , optTableOfContents = False

177+ , optTemplate = ""

176 , optVariables = []

178 , optVariables = []

177 , optIncludeInHeader = ""

179 , optIncludeInHeader = ""

178 , optIncludeBeforeBody = ""

180 , optIncludeBeforeBody = ""

@@ -334,13 +336,22 @@ options =

334 (\opt -> return opt { optTableOfContents = True }))

336 (\opt -> return opt { optTableOfContents = True }))

335 "" -- "Include table of contents"

337 "" -- "Include table of contents"

336

338

339+ , Option "" ["template"]

340+ (ReqArg

341+ (\arg opt -> do

342+ text <- readFile arg

343+ return opt{ optTemplate = text,

344+ optStandalone = True })

345+ "FILENAME")

346+ "" -- "Use custom template"

347+

337 , Option "c" ["css"]

348 , Option "c" ["css"]

338 (ReqArg

349 (ReqArg

339 (\arg opt -> do

350 (\arg opt -> do

340 let old = optCSS opt

351 let old = optCSS opt

341 return opt { optCSS = old ++ [arg],

352 return opt { optCSS = old ++ [arg],

342 optStandalone = True })

353 optStandalone = True })

343− "CSS")

354+ "URL")

344 "" -- "Link to CSS style sheet"

355 "" -- "Link to CSS style sheet"

345

356

346 , Option "H" ["include-in-header"]

357 , Option "H" ["include-in-header"]

@@ -536,6 +547,7 @@ main = do

536 , optCSS = css

547 , optCSS = css

537 , optVariables = variables

548 , optVariables = variables

538 , optTableOfContents = toc

549 , optTableOfContents = toc

550+ , optTemplate = template

539 , optIncludeInHeader = includeHeader

551 , optIncludeInHeader = includeHeader

540 , optIncludeBeforeBody = includeBefore

552 , optIncludeBeforeBody = includeBefore

541 , optIncludeAfterBody = includeAfter

553 , optIncludeAfterBody = includeAfter

@@ -623,7 +635,9 @@ main = do

623 let writerOptions = WriterOptions { writerStandalone = standalone',

635 let writerOptions = WriterOptions { writerStandalone = standalone',

624 writerTemplate = defaultTemplate,

636 writerTemplate = defaultTemplate,

625 writerVariables = variables',

637 writerVariables = variables',

638+ writerHeader = if null template

626− writerHeader = defaultTemplate, -- TODO remove

639+ then defaultTemplate

640+ else template,

627 writerTitlePrefix = titlePrefix,

641 writerTitlePrefix = titlePrefix,

628 writerTabStop = tabStop,

642 writerTabStop = tabStop,

629 writerTableOfContents = toc &&

643 writerTableOfContents = toc &&