From c602ed345959dbeb08533cd9c9c11f0604641c10 Mon Sep 17 00:00:00 2001 From: fiddlosopher Date: Thu, 31 Dec 2009 01:10:04 +0000 Subject: Added and documented --template option. git-svn-id: https://pandoc.googlecode.com/svn/trunk@1683 788f1e2b-df1e-0410-8736-df70ead52e1b --- README | 71 +++++++++++++++++++++++++++++++++++++++++++++ man/man1/markdown2pdf.1.md | 5 ++++ man/man1/pandoc.1.md | 72 +++++++++++++++++++++++++++++++++++++++++++++- src/pandoc.hs | 18 ++++++++++-- 4 files changed, 163 insertions(+), 3 deletions(-) diff --git a/README b/README index 2cb4618e4..139ad3c8a 100644 --- a/README +++ b/README @@ -282,6 +282,13 @@ For further documentation, see the `pandoc(1)` man page. one) in the output document. This option has no effect with `man`, `docbook`, or `s5` output formats. +`--template=`*file* +: uses *file* as a custom template for the generated document. Implies + `-s`. See [Templates](#templates) below for a description + of template syntax. If this option is not used, a default + template appropriate for the output format will be used. See also + `-D/--print-default-template`. + `-c` or `--css` *filename* : allows the user to specify a custom stylesheet that will be linked to 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. [gladTeX]: http://www.math.uio.no/~martingu/gladtex/index.html [mimeTeX]: http://www.forkosh.com/mimetex.html +Templates +========= + +When the `-s/--standalone` option is used, pandoc uses a template to +add header and footer material that is needed for a self-standing +document. To see the default template that is used, just type + + pandoc --print-default-template=FORMAT + +where `FORMAT` is the name of the output format. A custom template +can be specified using the `--template` option. + +Templates may contain *variables*. Variable names are sequences of +alphanumerics, `-`, and `_`, starting with a letter. A variable name +surrounded by `$` signs will be replaced by its value. For example, +the string `$title$` in + + $title$ + +will be replaced by the document title. + +Some variables are set automatically by pandoc. These vary somewhat +depending on the output format, but include: + +`before` +: contents specified by `-B/--include-before-body` +`after` +: contents specified by `-A/--include-after-body` +`legacy-header` +: contents specified by `-C/--custom-header` +`header-includes` +: contents specified by `-H/--include-in-header` +`toc` +: non-null value if `--toc/--table-of-contents` was specified +`body` +: body of document +`title` +: title of document, as specified in title block +`authors` +: authors of document, as specified in title block +`date` +: date of document, as specified in title block +`css` +: links to CSS files, as specified using `-c/--css` + +Variables may be set at the command line using the +`--set` option. This allows users to include custom variables in +their templates. + +Templates may contain conditionals. The syntax is as follows: + + $if(variable)$ + X + $else$ + Y + $endif$ + +This will include `X` in the template if `variable` has a non-null +value; otherwise it will include `Y`. `X` and `Y` are placeholders for +any valid template text, and may include interpolated variables or other +conditionals. The `$else$` section may be omitted. + +To write a literal `$` in a template, use `$$`. + Pandoc's markdown vs. standard markdown ======================================= diff --git a/man/man1/markdown2pdf.1.md b/man/man1/markdown2pdf.1.md index 0bc8329d7..66db76f4c 100644 --- a/man/man1/markdown2pdf.1.md +++ b/man/man1/markdown2pdf.1.md @@ -49,6 +49,11 @@ The following options are most relevant: -N, \--number-sections : Number section headings in LaTeX output. (Default is not to number them.) +\--template=*FILE* +: Use *FILE* as a custom template for the generated document. Implies + `-s`. See the section TEMPLATES in `pandoc`(1) for information about + template syntax. + -H *FILE*, \--include-in-header=*FILE* : Include (LaTeX) contents of *FILE* at the end of the header. Implies `-s`. diff --git a/man/man1/pandoc.1.md b/man/man1/pandoc.1.md index 69a678198..65e64d0ac 100644 --- a/man/man1/pandoc.1.md +++ b/man/man1/pandoc.1.md @@ -169,6 +169,12 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`. RTF) or an instruction to create one (LaTeX, reStructuredText). This option has no effect on man, DocBook, or S5 output. +\--template=*FILE* +: Use *FILE* as a custom template for the generated document. Implies + `-s`. See TEMPLATES below for a description of template syntax. If + this option is not used, a default template appropriate for the + output format will be used. See also `-D/--print-default-template`. + -c *CSS*, \--css=*CSS* : Link to a CSS style sheet. *CSS* is the pathname of the style sheet. @@ -184,7 +190,8 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`. -C *FILE*, \--custom-header=*FILE* : Use contents of *FILE* as the document header (overriding the default header, which can be printed by using the `-D` option). - Implies `-s`. + Implies `-s`. Note: This option is deprecated. Users should + transition to using `--template` instead. -D *FORMAT*, \--print-default-template=*FORMAT* : Print the default template for an output *FORMAT*. (See `-t` @@ -219,6 +226,69 @@ to Pandoc. Or use `html2markdown`(1), a wrapper around `pandoc`. -h, \--help : Show usage message. +# TEMPLATES + +When the `-s/--standalone` option is used, pandoc uses a template to +add header and footer material that is needed for a self-standing +document. To see the default template that is used, just type + + pandoc --print-default-template=FORMAT + +where `FORMAT` is the name of the output format. A custom template +can be specified using the `--template` option. + +Templates may contain *variables*. Variable names are sequences of +alphanumerics, `-`, and `_`, starting with a letter. A variable name +surrounded by `$` signs will be replaced by its value. For example, +the string `$title$` in + + $title$ + +will be replaced by the document title. + +Some variables are set automatically by pandoc. These vary somewhat +depending on the output format, but include: + +`before` +: contents specified by `-B/--include-before-body` +`after` +: contents specified by `-A/--include-after-body` +`legacy-header` +: contents specified by `-C/--custom-header` +`header-includes` +: contents specified by `-H/--include-in-header` +`toc` +: non-null value if `--toc/--table-of-contents` was specified +`body` +: body of document +`title` +: title of document, as specified in title block +`authors` +: authors of document, as specified in title block +`date` +: date of document, as specified in title block +`css` +: links to CSS files, as specified using `-c/--css` + +Variables may be set at the command line using the +`--set` option. This allows users to include custom variables in +their templates. + +Templates may contain conditionals. The syntax is as follows: + + $if(variable)$ + X + $else$ + Y + $endif$ + +This will include `X` in the template if `variable` has a non-null +value; otherwise it will include `Y`. `X` and `Y` are placeholders for +any valid template text, and may include interpolated variables or other +conditionals. The `$else$` section may be omitted. + +To write a literal `$` in a template, use `$$`. + # SEE ALSO `hsmarkdown`(1), diff --git a/src/pandoc.hs b/src/pandoc.hs index 125d964c1..71741dba3 100644 --- a/src/pandoc.hs +++ b/src/pandoc.hs @@ -135,6 +135,7 @@ data Opt = Opt , optParseRaw :: Bool -- ^ Parse unconvertable HTML and TeX , optCSS :: [String] -- ^ CSS file to link to , optTableOfContents :: Bool -- ^ Include table of contents + , optTemplate :: String -- ^ Custom template , optVariables :: [(String,String)] -- ^ Template variables to set , optIncludeInHeader :: String -- ^ File to include in header , optIncludeBeforeBody :: String -- ^ File to include at top of body @@ -173,6 +174,7 @@ defaultOpts = Opt , optParseRaw = False , optCSS = [] , optTableOfContents = False + , optTemplate = "" , optVariables = [] , optIncludeInHeader = "" , optIncludeBeforeBody = "" @@ -334,13 +336,22 @@ options = (\opt -> return opt { optTableOfContents = True })) "" -- "Include table of contents" + , Option "" ["template"] + (ReqArg + (\arg opt -> do + text <- readFile arg + return opt{ optTemplate = text, + optStandalone = True }) + "FILENAME") + "" -- "Use custom template" + , Option "c" ["css"] (ReqArg (\arg opt -> do let old = optCSS opt return opt { optCSS = old ++ [arg], optStandalone = True }) - "CSS") + "URL") "" -- "Link to CSS style sheet" , Option "H" ["include-in-header"] @@ -536,6 +547,7 @@ main = do , optCSS = css , optVariables = variables , optTableOfContents = toc + , optTemplate = template , optIncludeInHeader = includeHeader , optIncludeBeforeBody = includeBefore , optIncludeAfterBody = includeAfter @@ -623,7 +635,9 @@ main = do let writerOptions = WriterOptions { writerStandalone = standalone', writerTemplate = defaultTemplate, writerVariables = variables', - writerHeader = defaultTemplate, -- TODO remove + writerHeader = if null template + then defaultTemplate + else template, writerTitlePrefix = titlePrefix, writerTabStop = tabStop, writerTableOfContents = toc && -- cgit v1.2.3