#doc:name(scribble/programs/template/tplexp/index.html):template(basic.template)#

-- only set for top level index page
--#topLevelPage:true#
-- only set for pages having an index parent between themselves and the root
#parentTarget:../index.html#
#parentName:Template#

-- the default background is an orange to black fade. Set this to override.
--#backgroundImage:black_orangetoblack.jpg#

-- include final '/' separator
#pathToRoot:../../../../#

#pageTitle:tplexp#
-- default width is 40%: define to override
--#titleWidth:40%#

-- navigationBar clump: one row for each entry
-- simple rows define navigationName, navigationTarget
-- image rows also define navigationImgName, navigationImgX, navigationImgY,
--      and navigationImgAlt
-- all rows may define navigationHidden to comment out link definitions

#clump:name(navigationBar)#

#row#
-- URL to navigate to
#navigationTarget:#symbols#
-- navigation text displayed in bar
#navigationName:Symbol File#
-- define to hide navigation potential (eg if content not ready yet)
--#navigationHidden:true#
#endrow#

#row#
-- URL to navigate to
#navigationTarget:#usage#
-- navigation text displayed in bar
#navigationName:How I Use It#
-- define to hide navigation potential (eg if content not ready yet)
--#navigationHidden:true#
#endrow#

#row#
-- URL to navigate to
#navigationTarget:#licence#
-- navigation text displayed in bar
#navigationName:Licence#
-- define to hide navigation potential (eg if content not ready yet)
--#navigationHidden:true#
#endrow#

#endclump#

-- pageSection clump: one row for each text section
#clump:name(pageSection)#

#row#
-- title of section
#sectionTitle:What It Is#
-- defines bookmark within page for this section (used in some nav bars)
--#sectionTarget:#
-- the text of the section
#sectionText:
<p><code>tplexp</code> is a program which takes two inputs: a template file,
and a symbol file defining token values for that template. It requires
Template.pm to be in the library path.
</p>

<p>The usage text for this tool is:
</p>

<blockquote><pre>        tplexp <symbol file> [-t <template file>] [-odir <output dir>]
                [-dir <template dir>] [--help] [-?]
... where <template dir> defaults to '.'
</pre></blockquote>

<p>I present this program as an example of using Template.pm, not as any kind
of example of how to write a parser. Really, don't use this as an example of
how to write a parser, or a Perl program in general.
</p>

<p>Get <a href="tplexp"><code>tplexp</code></a>.
</p>

#
-- specifies the font size to be used for this section
#sectionFontSize:+1#
-- define if a 'top' button is to appear in the margin
-- note that the first row of the text table includes the nav bar table, which
-- means that the opening section must either be very long or not have a top
-- button following it, otherwise things look a bit strange.
--#topNavigation:true#
-- define if the default horizontal rule is to be omitted
#omitSeparator:true#
#endrow#

#row#
-- title of section
#sectionTitle:Symbol File#
-- defines bookmark within page for this section (used in some nav bars)
#sectionTarget:symbols#
-- the text of the section
#sectionText:
<p>The syntax of the symbol files which <code>tplexp</code> reads are designed
to be simple to parse. They support setting multiline
strings, comments, and setting default output.
</p>

<p>The symbol file syntax is line-oriented. Blank lines are ignored (unless in
a multiline text definition) and all line content must start in column 1. The
line types are:
</p>

<ol>

<li><p><i>doc descriptor</i> - this is the first line in a symbol file and is
ignored if appearing elsewhere. It takes the form</p>

<blockquote><pre>#doc:name(&lt;output file&gt;):template(&lt;template file&gt;)#&nbsp;
</pre></blockquote>

<p>... where &lt;output file&gt; is the name of the file where the output
should be written (if this is omitted then it is written to stdout), and
&lt;template file&gt; is the name of the template file to be used to frame the
token values.
</p>

<li><p><i>comments</i> - any unrecognised lines are ignored, but by convention
comments start with "--".</p>

<li><p><i>token definitions</i> - the variable parts of the generated content.
These have the form:</p>

<blockquote><pre>#&lt;token name&gt;:&lt;value&gt;#&nbsp;
</pre></blockquote>

<p>... where &lt;value&gt; may be a short string or multiple lines. Multiline
values are terminated with a '#' on the end of the last line.  Thus:
</p>

<blockquote><pre>-- a simple token value
#characterName:Alf du Plex#&nbsp;
-- a multiline token value
#characterBio:Alf is a simple reporter on a newspaper when he is sent to the
Isle of Man to cover the TT races. One morning he wakes up next to a dead
body, and before he knows what is happening he is catapulted into combatting
an ancient evil, the evil which destroyed Atlantis!
#&nbsp;
</pre></blockquote>

<li><p><i>clumps</i> - clump data is defined using a clump construct. The
clump is opened by specifying its name in a <code>clump</code>, and ended with
an <code>endclump</code> line. The clump so defined is created as a token in
the current token context.</p>

<p>Clumps may be nested.</p>

<p>The clump constructs are of the form:</p>

<blockquote><pre>-- opening a clump
#clump:&lt;clump name&gt;#&nbsp;
-- closing a clump
#endclump#&nbsp;
</pre></blockquote>

<li><p><i>clump rows</i> - Each row of a clump must be defined. These are not
identified in any way, being simply added to the clump in the order they are
encountered. Row numbering is handled by Template.pm itself.</p>

<p>Rows may only be defined within a clump.</p>

<p>The row constructs are of the form:</p>

<blockquote><pre>-- opening a row
#row#&nbsp;
-- closing a row
#endrow#&nbsp;
</pre></blockquote>

<li><p><i>evaluated strings</i> - Perl code may be embedded within the symbol
file for evaluation at the time of the symbol file's reading. The content of
an <code>eval</code> construct may be be on one or multiple lines as with a
token definition, but the value is not the text but the result returned from
the Perl code. This value is assigned to a named token.</p>

<p>The eval construct is of the form:</p>

<blockquote><pre>#eval:name(&lt;token name&gt;):&lt;text&gt;#&nbsp;
</pre></blockquote>

<p>The text is evaluated as soon as the parsing of the construct has been
completed, that is after the terminating '#' is encountered.
</p>

<p><b>WARNING</b> - this construct is the least used and least tested of all
that are described here. Use extreme caution.</p>

</ol>

#
-- specifies the font size to be used for this section
#sectionFontSize:+1#
-- define if a 'top' button is to appear in the margin
-- note that the first row of the text table includes the nav bar table, which
-- means that the opening section must either be very long or not have a top
-- button following it, otherwise things look a bit strange.
--#topNavigation:true#
-- define if the default horizontal rule is to be omitted
#omitSeparator:true#
#endrow#

#row#
-- title of section
#sectionTitle:How I Use It#
-- defines bookmark within page for this section (used in some nav bars)
#sectionTarget:usage#
-- the text of the section
#sectionText:
<p>My primary use for <code>tplexp</code> is to generate most of
my static web content (anything that isn't a photo gallery). I use
<code>make</code> to control updates to the site and include a rule to go
from .symbol to .html.
</p>

<p>Take a look at the symbol file for this web page: <a
href="index.symbol">index.symbol</a> (<a href="basic.template">template</a>)
</p>

#
-- specifies the font size to be used for this section
#sectionFontSize:+1#
-- define if a 'top' button is to appear in the margin
-- note that the first row of the text table includes the nav bar table, which
-- means that the opening section must either be very long or not have a top
-- button following it, otherwise things look a bit strange.
--#topNavigation:true#
-- define if the default horizontal rule is to be omitted
#omitSeparator:true#
#endrow#

#row#
-- title of section
#sectionTitle:Licence#
-- defines bookmark within page for this section (used in some nav bars)
#sectionTarget:licence#
-- the text of the section
#sectionText:
<p>This software copyright (c) Duncan Ellis 1999-2005.
</p>

<p>This is freely distributable software, but I'd appreciate your passing any
fixes or improvements back to me so I can publish them here.</p>

<p>No warranty is offered for the fitness of this software for any particular
purpose. Use it at your own risk.</p>

#
-- specifies the font size to be used for this section
#sectionFontSize:+1#
-- define if a 'top' button is to appear in the margin
-- note that the first row of the text table includes the nav bar table, which
-- means that the opening section must either be very long or not have a top
-- button following it, otherwise things look a bit strange.
--#topNavigation:true#
-- define if the default horizontal rule is to be omitted
#omitSeparator:true#
#endrow#

#endclump#