git.iko.soy/typeable/pandoc
on master help sign in
Added and documented --template option.

git-svn-id: https://pandoc.googlecode.com/svn/trunk@1683 788f1e2b-df1e-0410-8736-df70ead52e1b

commitc602ed345959dbeb08533cd9c9c11f0604641c10 authorfiddlosopher <fiddlosopher@788f1e2b-df1e-0410-8736-df70ead52e1b> dateThu 31 Dec 2009, 01:10 (17 years ago) parent974bcea
4 files changed+163−3
compare with master
unifiedsplit
README+71 man/man1/markdown2pdf.1.md+5 man/man1/pandoc.1.md+71−1 src/pandoc.hs+16−2
README+71
@@ -282,6 +282,13 @@ For further documentation, see the `pandoc(1)` man page.
282282 one) in the output document. This option has no effect with `man`,
283283 `docbook`, or `s5` output formats.
284284
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+
285292`-c` or `--css` *filename*
286293: allows the user to specify a custom stylesheet that will be linked to
287294 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.
437444[gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html
438445[mimeTeX]: http://www.forkosh.com/mimetex.html
439446
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+
440511Pandoc's markdown vs. standard markdown
441512=======================================
442513
man/man1/markdown2pdf.1.md+5
@@ -49,6 +49,11 @@ The following options are most relevant:
4949-N, \--number-sections
5050: Number section headings in LaTeX output. (Default is not to number them.)
5151
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+
5257-H *FILE*, \--include-in-header=*FILE*
5358: Include (LaTeX) contents of *FILE* at the end of the header. Implies
5459 `-s`.
man/man1/pandoc.1.md+71−1
@@ -169,6 +169,12 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.
169169 RTF) or an instruction to create one (LaTeX, reStructuredText).
170170 This option has no effect on man, DocBook, or S5 output.
171171
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+
172178-c *CSS*, \--css=*CSS*
173179: Link to a CSS style sheet. *CSS* is the pathname of the style sheet.
174180
@@ -184,7 +190,8 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.
184190-C *FILE*, \--custom-header=*FILE*
185191: Use contents of *FILE* as the document header (overriding the
186192 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.
188195
189196-D *FORMAT*, \--print-default-template=*FORMAT*
190197: Print the default template for an output *FORMAT*. (See `-t`
@@ -219,6 +226,69 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`.
219226-h, \--help
220227: Show usage message.
221228
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+
222292# SEE ALSO
223293
224294`hsmarkdown`(1),
src/pandoc.hs+16−2
@@ -135,6 +135,7 @@ data Opt = Opt
135135 , optParseRaw :: Bool -- ^ Parse unconvertable HTML and TeX
136136 , optCSS :: [String] -- ^ CSS file to link to
137137 , optTableOfContents :: Bool -- ^ Include table of contents
138+ , optTemplate :: String -- ^ Custom template
138139 , optVariables :: [(String,String)] -- ^ Template variables to set
139140 , optIncludeInHeader :: String -- ^ File to include in header
140141 , optIncludeBeforeBody :: String -- ^ File to include at top of body
@@ -173,6 +174,7 @@ defaultOpts = Opt
173174 , optParseRaw = False
174175 , optCSS = []
175176 , optTableOfContents = False
177+ , optTemplate = ""
176178 , optVariables = []
177179 , optIncludeInHeader = ""
178180 , optIncludeBeforeBody = ""
@@ -334,13 +336,22 @@ options =
334336 (\opt -> return opt { optTableOfContents = True }))
335337 "" -- "Include table of contents"
336338
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+
337348 , Option "c" ["css"]
338349 (ReqArg
339350 (\arg opt -> do
340351 let old = optCSS opt
341352 return opt { optCSS = old ++ [arg],
342353 optStandalone = True })
343− "CSS")
354+ "URL")
344355 "" -- "Link to CSS style sheet"
345356
346357 , Option "H" ["include-in-header"]
@@ -536,6 +547,7 @@ main = do
536547 , optCSS = css
537548 , optVariables = variables
538549 , optTableOfContents = toc
550+ , optTemplate = template
539551 , optIncludeInHeader = includeHeader
540552 , optIncludeBeforeBody = includeBefore
541553 , optIncludeAfterBody = includeAfter
@@ -623,7 +635,9 @@ main = do
623635 let writerOptions = WriterOptions { writerStandalone = standalone',
624636 writerTemplate = defaultTemplate,
625637 writerVariables = variables',
626− writerHeader = defaultTemplate, -- TODO remove
638+ writerHeader = if null template
639+ then defaultTemplate
640+ else template,
627641 writerTitlePrefix = titlePrefix,
628642 writerTabStop = tabStop,
629643 writerTableOfContents = toc &&