local-lib5/man/man3/Template::Tools::ttree.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Tools::ttree 3"
 132 .TH Template::Tools::ttree 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Tools::ttree \- Process entire directory trees of templates
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    ttree [options] [files]
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 The \fIttree\fR script is used to process entire directory trees containing
 143 template files.  The resulting output from processing each file is then
 144 written to a corresponding file in a destination directory.  The script
 145 compares the modification times of source and destination files (where
 146 they already exist) and processes only those files that have been modified.
 147 In other words, it is the equivalent of 'make' for the Template Toolkit.
 148 .PP
 149 It supports a number of options which can be used to configure
 150 behaviour, define locations and set Template Toolkit options.  The
 151 script first reads the \fI.ttreerc\fR configuration file in the \s-1HOME\s0
 152 directory, or an alternative file specified in the \s-1TTREERC\s0 environment
 153 variable.  Then, it processes any command line arguments, including
 154 any additional configuration files specified via the \f(CW\*(C`\-f\*(C'\fR (file)
 155 option.
 156 .Sh "The \fI.ttreerc\fP Configuration File"
 157 .IX Subsection "The .ttreerc Configuration File"
 158 When you run \fIttree\fR for the first time it will ask you if you want
 159 it to create a \fI.ttreerc\fR file for you.  This will be created in your
 160 home directory.
 161 .PP
 162 .Vb 4
 163 \&    $ ttree
 164 \&    Do you want me to create a sample '.ttreerc' file for you?
 165 \&    (file: /home/abw/.ttreerc)   [y/n]: y
 166 \&    /home/abw/.ttreerc created.  Please edit accordingly and re\-run ttree
 167 .Ve
 168 .PP
 169 The purpose of this file is to set any \fIglobal\fR configuration options
 170 that you want applied \fIevery\fR time \fIttree\fR is run.  For example, you
 171 can use the \f(CW\*(C`ignore\*(C'\fR and \f(CW\*(C`copy\*(C'\fR option to provide regular expressions
 172 that specify which files should be ignored and which should be copied
 173 rather than being processed as templates.  You may also want to set
 174 flags like \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`recurse\*(C'\fR according to your preference.
 175 .PP
 176 A minimal \fI.ttreerc\fR:
 177 .PP
 178 .Vb 4
 179 \&    # ignore these files
 180 \&    ignore = \eb(CVS|RCS)\eb
 181 \&    ignore = ^#
 182 \&    ignore = ~$
 183 .Ve
 184 .PP
 185 .Vb 2
 186 \&    # copy these files
 187 \&    copy   = \e.(gif|png|jpg|pdf)$
 188 .Ve
 189 .PP
 190 .Vb 2
 191 \&    # recurse into directories
 192 \&    recurse
 193 .Ve
 194 .PP
 195 .Vb 2
 196 \&    # provide info about what's going on
 197 \&    verbose
 198 .Ve
 199 .PP
 200 In most cases, you'll want to create a different \fIttree\fR configuration
 201 file for each project you're working on.  The \f(CW\*(C`cfg\*(C'\fR option allows you
 202 to specify a directory where \fIttree\fR can find further configuration
 203 files.
 204 .PP
 205 .Vb 1
 206 \&    cfg = /home/abw/.ttree
 207 .Ve
 208 .PP
 209 The \f(CW\*(C`\-f\*(C'\fR command line option can be used to specify which configuration
 210 file should be used.  You can specify a filename using an absolute or
 211 relative path:
 212 .PP
 213 .Vb 3
 214 \&    $ ttree \-f /home/abw/web/example/etc/ttree.cfg
 215 \&    $ ttree \-f ./etc/ttree.cfg
 216 \&    $ ttree \-f ../etc/ttree.cfg
 217 .Ve
 218 .PP
 219 If the configuration file does not begin with \f(CW\*(C`/\*(C'\fR or \f(CW\*(C`.\*(C'\fR or something
 220 that looks like a MS-DOS absolute path (e.g. \f(CW\*(C`C:\e\eetc\e\ettree.cfg\*(C'\fR) then
 221 \&\fIttree\fR will look for it in the directory specified by the \f(CW\*(C`cfg\*(C'\fR option.
 222 .PP
 223 .Vb 1
 224 \&    $ ttree \-f test1          # /home/abw/.ttree/test1
 225 .Ve
 226 .PP
 227 The \f(CW\*(C`cfg\*(C'\fR option can only be used in the \fI.ttreerc\fR file.  All the
 228 other options can be used in the \fI.ttreerc\fR or any other \fIttree\fR
 229 configuration file.  They can all also be specified as command line
 230 options.
 231 .PP
 232 Remember that \fI.ttreerc\fR is always processed \fIbefore\fR any
 233 configuration file specified with the \f(CW\*(C`\-f\*(C'\fR option.  Certain options
 234 like \f(CW\*(C`lib\*(C'\fR can be used any number of times and accumulate their values.
 235 .PP
 236 For example, consider the following configuration files:
 237 .PP
 238 \&\fI/home/abw/.ttreerc\fR:
 239 .PP
 240 .Vb 2
 241 \&    cfg = /home/abw/.ttree
 242 \&    lib = /usr/local/tt2/templates
 243 .Ve
 244 .PP
 245 \&\fI/home/abw/.ttree/myconfig\fR:
 246 .PP
 247 .Vb 1
 248 \&    lib = /home/abw/web/example/templates/lib
 249 .Ve
 250 .PP
 251 When \fIttree\fR is invoked as follows:
 252 .PP
 253 .Vb 1
 254 \&    $ ttree \-f myconfig
 255 .Ve
 256 .PP
 257 the \f(CW\*(C`lib\*(C'\fR option will be set to the following directories:
 258 .PP
 259 .Vb 2
 260 \&    /usr/local/tt2/templates
 261 \&    /home/abw/web/example/templates/lib
 262 .Ve
 263 .PP
 264 Any templates located under \fI/usr/local/tt2/templates\fR will be used
 265 in preference to those located under
 266 \&\fI/home/abw/web/example/templates/lib\fR.  This may be what you want,
 267 but then again, it might not.  For this reason, it is good practice to
 268 keep the \fI.ttreerc\fR as simple as possible and use different
 269 configuration files for each \fIttree\fR project.
 270 .Sh "Directory Options"
 271 .IX Subsection "Directory Options"
 272 The \f(CW\*(C`src\*(C'\fR option is used to define the directory containing the
 273 source templates to be processed.  It can be provided as a command
 274 line option or in a configuration file as shown here:
 275 .PP
 276 .Vb 1
 277 \&    src = /home/abw/web/example/templates/src
 278 .Ve
 279 .PP
 280 Each template in this directory typically corresponds to a single
 281 web page or other document.
 282 .PP
 283 The \f(CW\*(C`dest\*(C'\fR option is used to specify the destination directory for the
 284 generated output.
 285 .PP
 286 .Vb 1
 287 \&    dest = /home/abw/web/example/html
 288 .Ve
 289 .PP
 290 The \f(CW\*(C`lib\*(C'\fR option is used to define one or more directories containing
 291 additional library templates.  These templates are not documents in
 292 their own right and typically comprise of smaller, modular components
 293 like headers, footers and menus that are incorporated into pages templates.
 294 .PP
 295 .Vb 2
 296 \&    lib = /home/abw/web/example/templates/lib
 297 \&    lib = /usr/local/tt2/templates
 298 .Ve
 299 .PP
 300 The \f(CW\*(C`lib\*(C'\fR option can be used repeatedly to add further directories to
 301 the search path.
 302 .PP
 303 A list of templates can be passed to \fIttree\fR as command line arguments.
 304 .PP
 305 .Vb 1
 306 \&    $ ttree foo.html bar.html
 307 .Ve
 308 .PP
 309 It looks for these templates in the \f(CW\*(C`src\*(C'\fR directory and processes them
 310 through the Template Toolkit, using any additional template components
 311 from the \f(CW\*(C`lib\*(C'\fR directories.  The generated output is then written to
 312 the corresponding file in the \f(CW\*(C`dest\*(C'\fR directory.
 313 .PP
 314 If \fIttree\fR is invoked without explicitly specifying any templates
 315 to be processed then it will process every file in the \f(CW\*(C`src\*(C'\fR directory.
 316 If the \f(CW\*(C`\-r\*(C'\fR (recurse) option is set then it will additionally iterate
 317 down through sub-directories and process and other template files it finds
 318 therein.
 319 .PP
 320 .Vb 1
 321 \&    $ ttree \-r
 322 .Ve
 323 .PP
 324 If a template has been processed previously, \fIttree\fR will compare the
 325 modification times of the source and destination files.  If the source
 326 template (or one it is dependant on) has not been modified more
 327 recently than the generated output file then \fIttree\fR will not process
 328 it.  The \fI\-a\fR (all) option can be used to force \fIttree\fR to process
 329 all files regardless of modification time.
 330 .PP
 331 .Vb 1
 332 \&    $ tree \-a
 333 .Ve
 334 .PP
 335 Any templates explicitly named as command line argument are always
 336 processed and the modification time checking is bypassed.
 337 .Sh "File Options"
 338 .IX Subsection "File Options"
 339 The \f(CW\*(C`ignore\*(C'\fR, \f(CW\*(C`copy\*(C'\fR and \f(CW\*(C`accept\*(C'\fR options are used to specify Perl
 340 regexen to filter file names.  Files that match any of the \f(CW\*(C`ignore\*(C'\fR
 341 options will not be processed.  Remaining files that match any of the
 342 \&\f(CW\*(C`copy\*(C'\fR regexen will be copied to the destination directory.  Remaining
 343 files that then match any of the \f(CW\*(C`accept\*(C'\fR criteria are then processed
 344 via the Template Toolkit.  If no \f(CW\*(C`accept\*(C'\fR parameter is specified then
 345 all files will be accepted for processing if not already copied or
 346 ignored.
 347 .PP
 348 .Vb 4
 349 \&    # ignore these files
 350 \&    ignore = \eb(CVS|RCS)\eb
 351 \&    ignore = ^#
 352 \&    ignore = ~$
 353 .Ve
 354 .PP
 355 .Vb 2
 356 \&    # copy these files
 357 \&    copy   = \e.(gif|png|jpg|pdf)$
 358 .Ve
 359 .PP
 360 .Vb 2
 361 \&    # accept only .tt2 templates
 362 \&    accept = \e.tt2$
 363 .Ve
 364 .PP
 365 The \f(CW\*(C`suffix\*(C'\fR option is used to define mappings between the file
 366 extensions for source templates and the generated output files.  The
 367 following example specifies that source templates with a \f(CW\*(C`.tt2\*(C'\fR
 368 suffix should be output as \f(CW\*(C`.html\*(C'\fR files:
 369 .PP
 370 .Vb 1
 371 \&    suffix tt2=html
 372 .Ve
 373 .PP
 374 Or on the command line,
 375 .PP
 376 .Vb 1
 377 \&    \-\-suffix tt2=html
 378 .Ve
 379 .PP
 380 You can provide any number of different suffix mappings by repeating
 381 this option.
 382 .Sh "Template Dependencies"
 383 .IX Subsection "Template Dependencies"
 384 The \f(CW\*(C`depend\*(C'\fR and \f(CW\*(C`depend_file\*(C'\fR options allow you to specify
 385 how any given template file depends on another file or group of files.
 386 The \f(CW\*(C`depend\*(C'\fR option is used to express a single dependency.
 387 .PP
 388 .Vb 1
 389 \&  $ ttree \-\-depend foo=bar,baz
 390 .Ve
 391 .PP
 392 This command line example shows the \f(CW\*(C`\-\-depend\*(C'\fR option being used to
 393 specify that the \fIfoo\fR file is dependant on the \fIbar\fR and \fIbaz\fR
 394 templates.  This option can be used many time on the command line:
 395 .PP
 396 .Vb 1
 397 \&  $ ttree \-\-depend foo=bar,baz \-\-depend crash=bang,wallop
 398 .Ve
 399 .PP
 400 or in a configuration file:
 401 .PP
 402 .Vb 2
 403 \&  depend foo=bar,baz
 404 \&  depend crash=bang,wallop
 405 .Ve
 406 .PP
 407 The file appearing on the left of the \f(CW\*(C`=\*(C'\fR is specified relative to
 408 the \f(CW\*(C`src\*(C'\fR or \f(CW\*(C`lib\*(C'\fR directories.  The file(s) appearing on the right
 409 can be specified relative to any of these directories or as absolute
 410 file paths.
 411 .PP
 412 For example:
 413 .PP
 414 .Vb 1
 415 \&  $ ttree \-\-depend foo=bar,/tmp/baz
 416 .Ve
 417 .PP
 418 To define a dependency that applies to all files, use \f(CW\*(C`*\*(C'\fR on the
 419 left of the \f(CW\*(C`=\*(C'\fR.
 420 .PP
 421 .Vb 1
 422 \&  $ ttree \-\-depend *=header,footer
 423 .Ve
 424 .PP
 425 or in a configuration file:
 426 .PP
 427 .Vb 1
 428 \&  depend *=header,footer
 429 .Ve
 430 .PP
 431 Any templates that are defined in the \f(CW\*(C`pre_process\*(C'\fR, \f(CW\*(C`post_process\*(C'\fR,
 432 \&\f(CW\*(C`process\*(C'\fR or \f(CW\*(C`wrapper\*(C'\fR options will automatically be added to the
 433 list of global dependencies that apply to all templates.
 434 .PP
 435 The \f(CW\*(C`depend_file\*(C'\fR option can be used to specify a file that contains
 436 dependency information.
 437 .PP
 438 .Vb 1
 439 \&    $ ttree \-\-depend_file=/home/abw/web/example/etc/ttree.dep
 440 .Ve
 441 .PP
 442 Here is an example of a dependency file:
 443 .PP
 444 .Vb 1
 445 \&   # This is a comment. It is ignored.
 446 .Ve
 447 .PP
 448 .Vb 1
 449 \&   index.html: header footer menubar
 450 .Ve
 451 .PP
 452 .Vb 1
 453 \&   header: titlebar hotlinks
 454 .Ve
 455 .PP
 456 .Vb 1
 457 \&   menubar: menuitem
 458 .Ve
 459 .PP
 460 .Vb 3
 461 \&   # spanning multiple lines with the backslash
 462 \&   another.html: header footer menubar \e
 463 \&   sidebar searchform
 464 .Ve
 465 .PP
 466 Lines beginning with the \f(CW\*(C`#\*(C'\fR character are comments and are ignored.
 467 Blank lines are also ignored.  All other lines should provide a
 468 filename followed by a colon and then a list of dependant files
 469 separated by whitespace, commas or both.  Whitespace around the colon
 470 is also optional.  Lines ending in the \f(CW\*(C`\e\*(C'\fR character are continued
 471 onto the following line.
 472 .PP
 473 Files that contain spaces can be quoted. That is only necessary
 474 for files after the colon (':'). The file before the colon may be
 475 quoted if it contains a colon.
 476 .PP
 477 As with the command line options, the \f(CW\*(C`*\*(C'\fR character can be used
 478 as a wildcard to specify a dependency for all templates.
 479 .PP
 480 .Vb 1
 481 \&    * : config,header
 482 .Ve
 483 .Sh "Template Toolkit Options"
 484 .IX Subsection "Template Toolkit Options"
 485 \&\fIttree\fR also provides access to the usual range of Template Toolkit
 486 options.  For example, the \f(CW\*(C`\-\-pre_chomp\*(C'\fR and \f(CW\*(C`\-\-post_chomp\*(C'\fR \fIttree\fR
 487 options correspond to the \f(CW\*(C`PRE_CHOMP\*(C'\fR and \f(CW\*(C`POST_CHOMP\*(C'\fR options.
 488 .PP
 489 Run \f(CW\*(C`ttree \-h\*(C'\fR for a summary of the options available.
 490 .SH "AUTHORS"
 491 .IX Header "AUTHORS"
 492 Andy Wardley <abw@wardley.org>
 493 .PP
 494 <http://www.wardley.org>
 495 .PP
 496 With contributions from Dylan William Hardison (support for
 497 dependencies), Bryce Harrington (\f(CW\*(C`absolute\*(C'\fR and \f(CW\*(C`relative\*(C'\fR options),
 498 Mark Anderson (\f(CW\*(C`suffix\*(C'\fR and \f(CW\*(C`debug\*(C'\fR options), Harald Joerg and Leon
 499 Brocard who gets everywhere, it seems.
 500 .SH "COPYRIGHT"
 501 .IX Header "COPYRIGHT"
 502 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 503 .PP
 504 This module is free software; you can redistribute it and/or
 505 modify it under the same terms as Perl itself.
 506 .SH "SEE ALSO"
 507 .IX Header "SEE ALSO"
 508 Template::Tools::tpage