Commit | Line | Data |
3fea05b9 |
1 | =head1 NAME |
2 | |
3 | Template::Tools::ttree - Process entire directory trees of templates |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | ttree [options] [files] |
8 | |
9 | =head1 DESCRIPTION |
10 | |
11 | The F<ttree> script is used to process entire directory trees containing |
12 | template files. The resulting output from processing each file is then |
13 | written to a corresponding file in a destination directory. The script |
14 | compares the modification times of source and destination files (where |
15 | they already exist) and processes only those files that have been modified. |
16 | In other words, it is the equivalent of 'make' for the Template Toolkit. |
17 | |
18 | It supports a number of options which can be used to configure |
19 | behaviour, define locations and set Template Toolkit options. The |
20 | script first reads the F<.ttreerc> configuration file in the HOME |
21 | directory, or an alternative file specified in the TTREERC environment |
22 | variable. Then, it processes any command line arguments, including |
23 | any additional configuration files specified via the C<-f> (file) |
24 | option. |
25 | |
26 | =head2 The F<.ttreerc> Configuration File |
27 | |
28 | When you run F<ttree> for the first time it will ask you if you want |
29 | it to create a F<.ttreerc> file for you. This will be created in your |
30 | home directory. |
31 | |
32 | $ ttree |
33 | Do you want me to create a sample '.ttreerc' file for you? |
34 | (file: /home/abw/.ttreerc) [y/n]: y |
35 | /home/abw/.ttreerc created. Please edit accordingly and re-run ttree |
36 | |
37 | The purpose of this file is to set any I<global> configuration options |
38 | that you want applied I<every> time F<ttree> is run. For example, you |
39 | can use the C<ignore> and C<copy> option to provide regular expressions |
40 | that specify which files should be ignored and which should be copied |
41 | rather than being processed as templates. You may also want to set |
42 | flags like C<verbose> and C<recurse> according to your preference. |
43 | |
44 | A minimal F<.ttreerc>: |
45 | |
46 | # ignore these files |
47 | ignore = \b(CVS|RCS)\b |
48 | ignore = ^# |
49 | ignore = ~$ |
50 | |
51 | # copy these files |
52 | copy = \.(gif|png|jpg|pdf)$ |
53 | |
54 | # recurse into directories |
55 | recurse |
56 | |
57 | # provide info about what's going on |
58 | verbose |
59 | |
60 | In most cases, you'll want to create a different F<ttree> configuration |
61 | file for each project you're working on. The C<cfg> option allows you |
62 | to specify a directory where F<ttree> can find further configuration |
63 | files. |
64 | |
65 | cfg = /home/abw/.ttree |
66 | |
67 | The C<-f> command line option can be used to specify which configuration |
68 | file should be used. You can specify a filename using an absolute or |
69 | relative path: |
70 | |
71 | $ ttree -f /home/abw/web/example/etc/ttree.cfg |
72 | $ ttree -f ./etc/ttree.cfg |
73 | $ ttree -f ../etc/ttree.cfg |
74 | |
75 | If the configuration file does not begin with C</> or C<.> or something |
76 | that looks like a MS-DOS absolute path (e.g. C<C:\\etc\\ttree.cfg>) then |
77 | F<ttree> will look for it in the directory specified by the C<cfg> option. |
78 | |
79 | $ ttree -f test1 # /home/abw/.ttree/test1 |
80 | |
81 | The C<cfg> option can only be used in the F<.ttreerc> file. All the |
82 | other options can be used in the F<.ttreerc> or any other F<ttree> |
83 | configuration file. They can all also be specified as command line |
84 | options. |
85 | |
86 | Remember that F<.ttreerc> is always processed I<before> any |
87 | configuration file specified with the C<-f> option. Certain options |
88 | like C<lib> can be used any number of times and accumulate their values. |
89 | |
90 | For example, consider the following configuration files: |
91 | |
92 | F</home/abw/.ttreerc>: |
93 | |
94 | cfg = /home/abw/.ttree |
95 | lib = /usr/local/tt2/templates |
96 | |
97 | F</home/abw/.ttree/myconfig>: |
98 | |
99 | lib = /home/abw/web/example/templates/lib |
100 | |
101 | When F<ttree> is invoked as follows: |
102 | |
103 | $ ttree -f myconfig |
104 | |
105 | the C<lib> option will be set to the following directories: |
106 | |
107 | /usr/local/tt2/templates |
108 | /home/abw/web/example/templates/lib |
109 | |
110 | Any templates located under F</usr/local/tt2/templates> will be used |
111 | in preference to those located under |
112 | F</home/abw/web/example/templates/lib>. This may be what you want, |
113 | but then again, it might not. For this reason, it is good practice to |
114 | keep the F<.ttreerc> as simple as possible and use different |
115 | configuration files for each F<ttree> project. |
116 | |
117 | =head2 Directory Options |
118 | |
119 | The C<src> option is used to define the directory containing the |
120 | source templates to be processed. It can be provided as a command |
121 | line option or in a configuration file as shown here: |
122 | |
123 | src = /home/abw/web/example/templates/src |
124 | |
125 | Each template in this directory typically corresponds to a single |
126 | web page or other document. |
127 | |
128 | The C<dest> option is used to specify the destination directory for the |
129 | generated output. |
130 | |
131 | dest = /home/abw/web/example/html |
132 | |
133 | The C<lib> option is used to define one or more directories containing |
134 | additional library templates. These templates are not documents in |
135 | their own right and typically comprise of smaller, modular components |
136 | like headers, footers and menus that are incorporated into pages templates. |
137 | |
138 | lib = /home/abw/web/example/templates/lib |
139 | lib = /usr/local/tt2/templates |
140 | |
141 | The C<lib> option can be used repeatedly to add further directories to |
142 | the search path. |
143 | |
144 | A list of templates can be passed to F<ttree> as command line arguments. |
145 | |
146 | $ ttree foo.html bar.html |
147 | |
148 | It looks for these templates in the C<src> directory and processes them |
149 | through the Template Toolkit, using any additional template components |
150 | from the C<lib> directories. The generated output is then written to |
151 | the corresponding file in the C<dest> directory. |
152 | |
153 | If F<ttree> is invoked without explicitly specifying any templates |
154 | to be processed then it will process every file in the C<src> directory. |
155 | If the C<-r> (recurse) option is set then it will additionally iterate |
156 | down through sub-directories and process and other template files it finds |
157 | therein. |
158 | |
159 | $ ttree -r |
160 | |
161 | If a template has been processed previously, F<ttree> will compare the |
162 | modification times of the source and destination files. If the source |
163 | template (or one it is dependant on) has not been modified more |
164 | recently than the generated output file then F<ttree> will not process |
165 | it. The F<-a> (all) option can be used to force F<ttree> to process |
166 | all files regardless of modification time. |
167 | |
168 | $ tree -a |
169 | |
170 | Any templates explicitly named as command line argument are always |
171 | processed and the modification time checking is bypassed. |
172 | |
173 | =head2 File Options |
174 | |
175 | The C<ignore>, C<copy> and C<accept> options are used to specify Perl |
176 | regexen to filter file names. Files that match any of the C<ignore> |
177 | options will not be processed. Remaining files that match any of the |
178 | C<copy> regexen will be copied to the destination directory. Remaining |
179 | files that then match any of the C<accept> criteria are then processed |
180 | via the Template Toolkit. If no C<accept> parameter is specified then |
181 | all files will be accepted for processing if not already copied or |
182 | ignored. |
183 | |
184 | # ignore these files |
185 | ignore = \b(CVS|RCS)\b |
186 | ignore = ^# |
187 | ignore = ~$ |
188 | |
189 | # copy these files |
190 | copy = \.(gif|png|jpg|pdf)$ |
191 | |
192 | # accept only .tt2 templates |
193 | accept = \.tt2$ |
194 | |
195 | The C<suffix> option is used to define mappings between the file |
196 | extensions for source templates and the generated output files. The |
197 | following example specifies that source templates with a C<.tt2> |
198 | suffix should be output as C<.html> files: |
199 | |
200 | suffix tt2=html |
201 | |
202 | Or on the command line, |
203 | |
204 | --suffix tt2=html |
205 | |
206 | You can provide any number of different suffix mappings by repeating |
207 | this option. |
208 | |
209 | =head2 Template Dependencies |
210 | |
211 | The C<depend> and C<depend_file> options allow you to specify |
212 | how any given template file depends on another file or group of files. |
213 | The C<depend> option is used to express a single dependency. |
214 | |
215 | $ ttree --depend foo=bar,baz |
216 | |
217 | This command line example shows the C<--depend> option being used to |
218 | specify that the F<foo> file is dependant on the F<bar> and F<baz> |
219 | templates. This option can be used many time on the command line: |
220 | |
221 | $ ttree --depend foo=bar,baz --depend crash=bang,wallop |
222 | |
223 | or in a configuration file: |
224 | |
225 | depend foo=bar,baz |
226 | depend crash=bang,wallop |
227 | |
228 | The file appearing on the left of the C<=> is specified relative to |
229 | the C<src> or C<lib> directories. The file(s) appearing on the right |
230 | can be specified relative to any of these directories or as absolute |
231 | file paths. |
232 | |
233 | For example: |
234 | |
235 | $ ttree --depend foo=bar,/tmp/baz |
236 | |
237 | To define a dependency that applies to all files, use C<*> on the |
238 | left of the C<=>. |
239 | |
240 | $ ttree --depend *=header,footer |
241 | |
242 | or in a configuration file: |
243 | |
244 | depend *=header,footer |
245 | |
246 | Any templates that are defined in the C<pre_process>, C<post_process>, |
247 | C<process> or C<wrapper> options will automatically be added to the |
248 | list of global dependencies that apply to all templates. |
249 | |
250 | The C<depend_file> option can be used to specify a file that contains |
251 | dependency information. |
252 | |
253 | $ ttree --depend_file=/home/abw/web/example/etc/ttree.dep |
254 | |
255 | Here is an example of a dependency file: |
256 | |
257 | # This is a comment. It is ignored. |
258 | |
259 | index.html: header footer menubar |
260 | |
261 | header: titlebar hotlinks |
262 | |
263 | menubar: menuitem |
264 | |
265 | # spanning multiple lines with the backslash |
266 | another.html: header footer menubar \ |
267 | sidebar searchform |
268 | |
269 | Lines beginning with the C<#> character are comments and are ignored. |
270 | Blank lines are also ignored. All other lines should provide a |
271 | filename followed by a colon and then a list of dependant files |
272 | separated by whitespace, commas or both. Whitespace around the colon |
273 | is also optional. Lines ending in the C<\> character are continued |
274 | onto the following line. |
275 | |
276 | Files that contain spaces can be quoted. That is only necessary |
277 | for files after the colon (':'). The file before the colon may be |
278 | quoted if it contains a colon. |
279 | |
280 | As with the command line options, the C<*> character can be used |
281 | as a wildcard to specify a dependency for all templates. |
282 | |
283 | * : config,header |
284 | |
285 | =head2 Template Toolkit Options |
286 | |
287 | F<ttree> also provides access to the usual range of Template Toolkit |
288 | options. For example, the C<--pre_chomp> and C<--post_chomp> F<ttree> |
289 | options correspond to the C<PRE_CHOMP> and C<POST_CHOMP> options. |
290 | |
291 | Run C<ttree -h> for a summary of the options available. |
292 | |
293 | =head1 AUTHORS |
294 | |
295 | Andy Wardley E<lt>abw@wardley.orgE<gt> |
296 | |
297 | L<http://www.wardley.org> |
298 | |
299 | With contributions from Dylan William Hardison (support for |
300 | dependencies), Bryce Harrington (C<absolute> and C<relative> options), |
301 | Mark Anderson (C<suffix> and C<debug> options), Harald Joerg and Leon |
302 | Brocard who gets everywhere, it seems. |
303 | |
304 | =head1 COPYRIGHT |
305 | |
306 | Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
307 | |
308 | This module is free software; you can redistribute it and/or |
309 | modify it under the same terms as Perl itself. |
310 | |
311 | =head1 SEE ALSO |
312 | |
313 | L<Template::Tools::tpage|tpage> |
314 | |