Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Added and documented --template option.

Browse source 
git-svn-id: https://pandoc.googlecode.com/svn/trunk@1683 788f1e2b-df1e-0410-8736-df70ead52e1b
This commit is contained in:
fiddlosopher 2009-12-31 01:10:04 +00:00
parent 974bceaac5
commit c602ed3459
4 changed files with 163 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
README
View file

@ -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
=======================================

5
man/man1/markdown2pdf.1.md
View file

@ -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`.

72
man/man1/pandoc.1.md
View file

@ -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),

18
src/pandoc.hs
View file

@ -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 &&