[Templates-cvs] cvs commit: Template2/docs/src/Tools tpage.html ttree.html
cvs@template-toolkit.org
cvs@template-toolkit.org
Tue, 06 Jan 2004 18:31:03 +0000
cvs 04/01/06 18:31:02
Modified: docs/src/Tools tpage.html ttree.html
Log:
* verion 2.11
Revision Changes Path
1.56 +3 -3 Template2/docs/src/Tools/tpage.html
Index: tpage.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Tools/tpage.html,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -r1.55 -r1.56
--- tpage.html 2003/07/24 16:16:17 1.55
+++ tpage.html 2004/01/06 18:31:02 1.56
@@ -73,13 +73,13 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-2.64, distributed as part of the
-Template Toolkit version 2.10, released on 24 July 2003.
+2.65, distributed as part of the
+Template Toolkit version 2.11, released on 06 January 2004.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2003 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.56 +288 -48 Template2/docs/src/Tools/ttree.html
Index: ttree.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Tools/ttree.html,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -r1.55 -r1.56
--- ttree.html 2003/07/24 16:16:17 1.55
+++ ttree.html 2004/01/06 18:31:02 1.56
@@ -17,9 +17,15 @@
subs = [];
PROCESS tocitem
title ="DESCRIPTION"
- subs = [];
+ subs = [
+ "The <file>.ttreerc</file> Configuration File",
+ "Directory Options",
+ "File Options",
+ "Template Dependencies",
+ "Template Toolkit Options"
+ ];
PROCESS tocitem
- title ="AUTHOR"
+ title ="AUTHORS"
subs = [];
PROCESS tocitem
title ="VERSION"
@@ -53,84 +59,318 @@
script first reads the <file>.ttreerc</file> configuration file in the HOME
directory, or an alternative file specified in the TTREERC environment
variable. Then, it processes any command line arguments, including
-any additional configuration files specified via the <b>-f</b> (file) option.
+any additional configuration files specified via the <code>'-f'</code> (file)
+option.
+</p>
+[% WRAPPER subsection
+ title = "The <file>.ttreerc</file> Configuration File"
+-%]<p>
+When you run <file>ttree</file> for the first time it will ask you if you want
+it to create a <file>.ttreerc</file> file for you. This will be created in your
+home directory.
+</p>
+<pre> $ ttree
+ Do you want me to create a sample '.ttreerc' file for you?
+ (file: /home/abw/.ttreerc) [y/n]: y
+ /home/abw/.ttreerc created. Please edit accordingly and re-run ttree</pre>
+<p>
+The purpose of this file is to set any <i>global</i> configuration options
+that you want applied <i>every</i> time <file>ttree</file> is run. For example, you
+can use the <code>'ignore'</code> and <code>'copy'</code> option to provide regular expressions
+that specify which files should be ignored and which should be copied
+rather than being processed as templates. You may also want to set
+flags like <code>'verbose'</code> and <code>'recurse'</code> according to your preference.
</p>
<p>
-A typical <file>.ttreerc</file> file might look like this:
+A minimal <file>.ttreerc</file>:
</p>
-<pre> src = /home/abw/websrc/doc
- dest = /home/abw/public_html
- lib = /home/abw/websrc/lib
- lib = /usr/local/templates/lib
- cfg = /home/abw/.ttree
+<pre> # ignore these files
ignore = \b(CVS|RCS)\b
ignore = ^#
- copy = \.(gif|png)$
- accept = \.[ah]tml$</pre>
+ ignore = ~$</pre>
+<pre> # copy these files
+ copy = \.(gif|png|jpg|pdf)$ </pre>
+<pre> # recurse into directories
+ recurse</pre>
+<pre> # provide info about what's going on
+ verbose</pre>
+<p>
+In most cases, you'll want to create a different <file>ttree</file> configuration
+file for each project you're working on. The <code>'cfg'</code> option allows you
+to specify a directory where <file>ttree</file> can find further configuration
+files.
+</p>
+<pre> cfg = /home/abw/.ttree</pre>
+<p>
+The <code>'-f'</code> command line option can be used to specify which configuration
+file should be used. You can specify a filename using an absolute or
+relative path:
+</p>
+<pre> $ ttree -f /home/abw/web/example/etc/ttree.cfg
+ $ ttree -f ./etc/ttree.cfg
+ $ ttree -f ../etc/ttree.cfg</pre>
+<p>
+If the configuration file does not begin with <code>'/'</code> or <code>'.'</code> or something
+that looks like a MS-DOS absolute path (e.g. <code>'C:\\etc\\ttree.cfg'</code>) then
+<file>ttree</file> will look for it in the directory specified by the <code>'cfg'</code> option.
+</p>
+<pre> $ ttree -f test1 # /home/abw/.ttree/test1</pre>
+<p>
+The <code>'cfg'</code> option can only be used in the <file>.ttreerc</file> file. All the
+other options can be used in the <file>.ttreerc</file> or any other <file>ttree</file>
+configuration file. They can all also be specified as command line
+options.
+</p>
+<p>
+Remember that <file>.ttreerc</file> is always processed <i>before</i> any
+configuration file specified with the <code>'-f'</code> option. Certain options
+like <code>'lib'</code> can be used any number of times and accumulate their values.
+</p>
+<p>
+For example, consider the following configuration files:
+</p>
+<p>
+<file>/home/abw/.ttreerc</file>:
+</p>
+<pre> cfg = /home/abw/.ttree
+ lib = /usr/local/tt2/templates</pre>
+<p>
+<file>/home/abw/.ttree/myconfig</file>:
+</p>
+<pre> lib = /home/abw/web/example/templates/lib</pre>
+<p>
+When <file>ttree</file> is invoked as follows:
+</p>
+<pre> $ ttree -f myconfig</pre>
+<p>
+the <code>'lib'</code> option will be set to the following directories:
+</p>
+<pre> /usr/local/tt2/templates
+ /home/abw/web/example/templates/lib</pre>
+<p>
+Any templates located under <file>/usr/local/tt2/templates</file> will be used
+in preference to those located under
+<file>/home/abw/web/example/templates/lib</file>. This may be what you want,
+but then again, it might not. For this reason, it is good practice to
+keep the <file>.ttreerc</file> as simple as possible and use different
+configuration files for each <file>ttree</file> project.
+</p>
+[%- END %]
+[% WRAPPER subsection
+ title = "Directory Options"
+-%]<p>
+The <code>'src'</code> option is used to define the directory containing the
+source templates to be processed. It can be provided as a command
+line option or in a configuration file as shown here:
+</p>
+<pre> src = /home/abw/web/example/templates/src</pre>
+<p>
+Each template in this directory typically corresponds to a single
+web page or other document.
+</p>
+<p>
+The <code>'dest'</code> option is used to specify the destination directory for the
+generated output.
+</p>
+<pre> dest = /home/abw/web/example/html</pre>
+<p>
+The <code>'lib'</code> option is used to define one or more directories containing
+additional library templates. These templates are not documents in
+their own right and typically comprise of smaller, modular components
+like headers, footers and menus that are incorporated into pages templates.
+</p>
+<pre> lib = /home/abw/web/example/templates/lib
+ lib = /usr/local/tt2/templates</pre>
+<p>
+The <code>'lib'</code> option can be used repeatedly to add further directories to
+the search path.
+</p>
+<p>
+A list of templates can be passed to <file>ttree</file> as command line arguments.
+</p>
+<pre> $ ttree foo.html bar.html</pre>
+<p>
+It looks for these templates in the <code>'src'</code> directory and processes them
+through the Template Toolkit, using any additional template components
+from the <code>'lib'</code> directories. The generated output is then written to
+the corresponding file in the <code>'dest'</code> directory.
+</p>
+<p>
+If <file>ttree</file> is invoked without explicitly specifying any templates
+to be processed then it will process every file in the <code>'src'</code> directory.
+If the <code>'-r'</code> (recurse) option is set then it will additionally iterate
+down through sub-directories and process and other template files it finds
+therein.
+</p>
+<pre> $ ttree -r</pre>
<p>
-The <b>src</b> option indicates a directory containing the template files
-to be processed. A list of files may be specified on the command line
-and each will be processed in turn, writing the generated output to a
-corresponding file in the <b>dest</b> directory. If no files are
-explicitly named then all files in the <b>src</b> directory will be
-processed. The <b>-r</b> (recurse) option will also cause sub-directories
-to be searched for files. A source file is only processed if it has a
-later modification time than any corresponding destination file.
-Files will always be processed, regardless of modification times, if
-they are named explicitly on the command line, or the <b>-a</b> (all)
-option is used.
-</p>
-<p>
-The <b>lib</b> option may be specified any number of times to indicate
-directories in which the Template Toolkit should look for other
-template files (INCLUDE_PATH) that it may need to INCLUDE or PROCESS,
-but don't represent complete documents that should be processed in
-their own right (e.g. headers, footers, menu). The <b>cfg</b> directory
-specifies the location of additional configuration files that may be
-loaded via the <b>-f</b> option.
+If a template has been processed previously, <file>ttree</file> will compare the
+modification times of the source and destination files. If the source
+template (or one it is dependant on) has not been modified more
+recently than the generated output file then <file>ttree</file> will not process
+it. The <file>-a</file> (all) option can be used to force <file>ttree</file> to process
+all files regardless of modification time.
</p>
+<pre> $ tree -a</pre>
<p>
-The <b>ignore</b>, <b>copy</b> and <b>accept</b> options are used to specify Perl
-regexen to filter file names. Files that match any of the <b>ignore</b>
+Any templates explicitly named as command line argument are always
+processed and the modification time checking is bypassed.
+</p>
+[%- END %]
+[% WRAPPER subsection
+ title = "File Options"
+-%]<p>
+The <code>'ignore'</code>, <code>'copy'</code> and <code>'accept'</code> options are used to specify Perl
+regexen to filter file names. Files that match any of the <code>'ignore'</code>
options will not be processed. Remaining files that match any of the
-<b>copy</b> regexen will be copied to the destination directory. Remaining
-files that then match any of the <b>accept</b> criteria are then processed
-via the Template Toolkit. If no <b>accept</b> parameter is specified then
+<code>'copy'</code> regexen will be copied to the destination directory. Remaining
+files that then match any of the <code>'accept'</code> criteria are then processed
+via the Template Toolkit. If no <code>'accept'</code> parameter is specified then
all files will be accepted for processing if not already copied or
- ignored.
+ignored.
</p>
+<pre> # ignore these files
+ ignore = \b(CVS|RCS)\b
+ ignore = ^#
+ ignore = ~$</pre>
+<pre> # copy these files
+ copy = \.(gif|png|jpg|pdf)$ </pre>
+<pre> # accept only .tt2 templates
+ accept = \.tt2$</pre>
<p>
-Additional options may be used to set Template Toolkit parameters.
+The <code>'suffix'</code> option is used to define mappings between the file
+extensions for source templates and the generated output files. The
+following example specifies that source templates with a <code>'.tt2'</code>
+suffix should be output as <code>'.html'</code> files:
+</p>
+<pre> suffix tt2=html</pre>
+<p>
+Or on the command line,
+</p>
+<pre> --suffix tt2=html</pre>
+<p>
+You can provide any number of different suffix mappings by repeating
+this option.
+</p>
+[%- END %]
+[% WRAPPER subsection
+ title = "Template Dependencies"
+-%]<p>
+The <code>'depend'</code> and <code>'depend_file'</code> options allow you to specify
+how any given template file depends on another file or group of files.
+The <code>'depend'</code> option is used to express a single dependency.
+</p>
+<pre> $ ttree --depend foo=bar,baz</pre>
+<p>
+This command line example shows the <code>'--depend'</code> option being used to
+specify that the <file>foo</file> file is dependant on the <file>bar</file> and <file>baz</file>
+templates. This option can be used many time on the command line:
+</p>
+<pre> $ ttree --depend foo=bar,baz --depend crash=bang,wallop</pre>
+<p>
+or in a configuration file:
+</p>
+<pre> depend foo=bar,baz
+ depend crash=bang,wallop</pre>
+<p>
+The file appearing on the left of the <code>'='</code> is specified relative to
+the <code>'src'</code> or <code>'lib'</code> directories. The file(s) appearing on the right
+can be specified relative to any of these directories or as absolute
+file paths.
+</p>
+<p>
For example:
+</p>
+<pre> $ ttree --depend foo=bar,/tmp/baz</pre>
+<p>
+To define a dependency that applies to all files, use <code>'*'</code> on the
+left of the <code>'='</code>.
+</p>
+<pre> $ ttree --depend *=header,footer</pre>
+<p>
+or in a configuration file:
+</p>
+<pre> depend *=header,footer</pre>
+<p>
+Any templates that are defined in the <code>'pre_process'</code>, <code>'post_process'</code>,
+<code>'process'</code> or <code>'wrapper'</code> options will automatically be added to the
+list of global dependencies that apply to all templates.
+</p>
+<p>
+The <code>'depend_file'</code> option can be used to specify a file that contains
+dependency information.
+</p>
+<pre> $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep</pre>
+<p>
+Here is an example of a dependency file:
+</p>
+<pre> # This is a comment. It is ignored.
+
+ index.html: header footer menubar
+
+ header: titlebar hotlinks
+
+ menubar: menuitem
+
+ # spanning multiple lines with the backslash
+ another.html: header footer menubar \
+ sidebar searchform</pre>
+<p>
+Lines beginning with the <code>'#'</code> character are comments and are ignored.
+Blank lines are also ignored. All other lines should provide a
+filename followed by a colon and then a list of dependant files
+separated by whitespace, commas or both. Whitespace around the colon
+is also optional. Lines ending in the <code>'\'</code> character are continued
+onto the following line.
</p>
-<pre> interpolate
- post_chomp
- pre_process = header
- post_process = footer
- perl5lib = /home/abw/lib/perl5</pre>
<p>
-See <b>ttree --help</b> for a summary of options.
+Files that contain spaces can be quoted. That is only necessary
+for files after the colon (':'). The file before the colon may be
+quoted if it contains a colon.
</p>
+<p>
+As with the command line options, the <code>'*'</code> character can be used
+as a wildcard to specify a dependency for all templates.
+</p>
+<pre> * : config,header</pre>
+[%- END %]
+[% WRAPPER subsection
+ title = "Template Toolkit Options"
+-%]<p>
+<file>ttree</file> also provides access to the usual range of Template Toolkit
+options. For example, the <code>'--pre_chomp'</code> and <code>'--post_chomp'</code> <file>ttree</file>
+options correspond to the <code>'PRE_CHOMP'</code> and <code>'POST_CHOMP'</code> options.
+</p>
+<p>
+Run <code>'ttree -h'</code> for a summary of the options available.
+</p>
+[%- END %]
[%- END %]
[% WRAPPER section
- title="AUTHOR"
+ title="AUTHORS"
-%]<p>
Andy Wardley <abw@andywardley.com>
</p>
<p>
[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
</p>
+<p>
+With contributions from Dylan William Hardison (support for
+dependencies), Bryce Harrington (<code>'absolute'</code> and <code>'relative'</code> options),
+Mark Anderson (<code>'suffix'</code> and <code>'debug'</code> options), Harald Joerg and Leon
+Brocard who gets everywhere, it seems.
+</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-2.64, distributed as part of the
-Template Toolkit version 2.10, released on 24 July 2003.
+2.65, distributed as part of the
+Template Toolkit version 2.11, released on 06 January 2004.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2003 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or