Added and documented --template option.

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

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>$title$</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>$title$</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 &&