| 1 | |||
| 2 | |||
| 3 | # = HISTORY SECTION ===================================================================== | ||
| 4 | |||
| 5 | # --------------------------------------------------------------------------------------- | ||
| 6 | # version | date | author | changes | ||
| 7 | # --------------------------------------------------------------------------------------- | ||
| 8 | # 0.02 |03.12.2005| JSTENZEL | producing better XHTML: empty tags closed (<tag />); | ||
| 9 | # 0.01 |08.07.2004| JSTENZEL | new. | ||
| 10 | # --------------------------------------------------------------------------------------- | ||
| 11 | |||
| 12 | # = POD SECTION ========================================================================= | ||
| 13 | |||
| 14 | =head1 NAME | ||
| 15 | |||
| 16 | B<PerlPoint::Template::Traditional> - PerlPoint template processor for traditional pp2html layouts | ||
| 17 | |||
| 18 | =head1 VERSION | ||
| 19 | |||
| 20 | This manual describes version B<0.02>. | ||
| 21 | |||
| 22 | =head1 SYNOPSIS | ||
| 23 | |||
| 24 | |||
| 25 | |||
| 26 | =head1 DESCRIPTION | ||
| 27 | |||
| 28 | |||
| 29 | =head1 METHODS | ||
| 30 | |||
| 31 | =cut | ||
| 32 | |||
| 33 | |||
| 34 | |||
| 35 | |||
| 36 | # check perl version | ||
| 37 | require 5.00503; | ||
| 38 | |||
| 39 | # = PACKAGE SECTION (internal helper package) ========================================== | ||
| 40 | |||
| 41 | # declare package | ||
| 42 | package PerlPoint::Template::Traditional; | ||
| 43 | |||
| 44 | # declare package version and author | ||
| 45 | $VERSION=0.02; | ||
| 46 | $AUTHOR=$AUTHOR='J. Stenzel (perl@jochen-stenzel.de), 2004-2006'; | ||
| 47 | |||
| 48 | |||
| 49 | # = PRAGMA SECTION ======================================================================= | ||
| 50 | |||
| 51 | # set pragmata | ||
| 52 | use strict; | ||
| 53 | |||
| 54 | # declare object data fields | ||
| 55 | use fields qw( | ||
| 56 | ); | ||
| 57 | |||
| 58 | # derive ... | ||
| 59 | use base qw(PerlPoint::Template); | ||
| 60 | |||
| 61 | |||
| 62 | # = LIBRARY SECTION ====================================================================== | ||
| 63 | |||
| 64 | # load modules | ||
| 65 | use Carp; | ||
| 66 | use File::Copy; | ||
| 67 | use File::Basename; | ||
| 68 | use POSIX qw(strftime); | ||
| 69 | use PerlPoint::Constants 0.17 qw(:templates); | ||
| 70 | |||
| 71 | |||
| 72 | # = CODE SECTION ========================================================================= | ||
| 73 | |||
| 74 | |||
| 75 | =pod | ||
| 76 | |||
| 77 | =head2 new() | ||
| 78 | |||
| 79 | |||
| 80 | B<Parameters:> | ||
| 81 | |||
| 82 | =over 4 | ||
| 83 | |||
| 84 | =item class | ||
| 85 | |||
| 86 | The class name. | ||
| 87 | |||
| 88 | =back | ||
| 89 | |||
| 90 | B<Returns:> the new object. | ||
| 91 | |||
| 92 | B<Example:> | ||
| 93 | |||
| 94 | |||
| 95 | =cut | ||
| 96 | sub new | ||
| 97 | { | ||
| 98 | # get parameter | ||
| 99 | my ($class, %params)=@_; | ||
| 100 | |||
| 101 | # check parameters | ||
| 102 | confess "[BUG] Missing class name.\n" unless $class; | ||
| 103 | |||
| 104 | # build and supply new object | ||
| 105 | fields::new($class); | ||
| 106 | } | ||
| 107 | |||
| 108 | |||
| 109 | # provide option declarations | ||
| 110 | sub declareOptions | ||
| 111 | { | ||
| 112 | # get and check parameters | ||
| 113 | (my __PACKAGE__ $me)=@_; | ||
| 114 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 115 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 116 | |||
| 117 | ( | ||
| 118 | # new options | ||
| 119 | [ | ||
| 120 | # template files: document templates (for files produced *once*) | ||
| 121 | "doc_template=s@", | ||
| 122 | |||
| 123 | # template files: header contents | ||
| 124 | "header_template=s", | ||
| 125 | "header_idx_template=s", | ||
| 126 | "header_toc_template=s", | ||
| 127 | |||
| 128 | # template files: body top | ||
| 129 | "top_template=s", | ||
| 130 | "top_idx_template=s", | ||
| 131 | "top_toc_template=s", | ||
| 132 | |||
| 133 | # template files: body bottom | ||
| 134 | "bottom_template=s", | ||
| 135 | "bottom_idx_template=s", | ||
| 136 | "bottom_toc_template=s", | ||
| 137 | |||
| 138 | # template files: navigation | ||
| 139 | "nav_template=s", | ||
| 140 | "nav_top_template=s", | ||
| 141 | "nav_bottom_template=s", | ||
| 142 | |||
| 143 | # template files: supplements | ||
| 144 | "supplement_template=s@", | ||
| 145 | "supplement_idx_template=s@", | ||
| 146 | "supplement_toc_template=s@", | ||
| 147 | |||
| 148 | # template strings | ||
| 149 | "bot_left_txt=s", | ||
| 150 | "bot_middle_txt=s", | ||
| 151 | "bot_right_txt=s", | ||
| 152 | "contents_header=s", | ||
| 153 | "index_header=s", | ||
| 154 | "label_contents=s", | ||
| 155 | "label_index=s", | ||
| 156 | "label_next=s", | ||
| 157 | "label_prev=s", | ||
| 158 | "top_left_txt=s", | ||
| 159 | "top_middle_txt=s", | ||
| 160 | "top_right_txt=s", | ||
| 161 | |||
| 162 | # logo | ||
| 163 | "logo_image_filename=s", | ||
| 164 | |||
| 165 | # links | ||
| 166 | "bootstrapaddress=s", # address of the first page of the site (not necessarily generated); | ||
| 167 | "startaddress=s", # base address of the site, like a servers address - used to build absolute links to our pages; | ||
| 168 | |||
| 169 | # link navigation | ||
| 170 | "linknavigation", | ||
| 171 | |||
| 172 | # tree applet support (in the tradition of pp2html) | ||
| 173 | "appletdir|applet_dir=s", # target applet directory (allow "applet_dir" for backwards compatibility with pp2html); | ||
| 174 | "appletref|applet_ref=s", # target applet directory reference (allow "applet_ref" for backwards compatibility with pp2html); | ||
| 175 | |||
| 176 | "tree_app_hint=s", # tree applet hint text, to be displayed if Java is deactivated; | ||
| 177 | "tree_app_height=s", # tree applet area height; | ||
| 178 | "tree_app_width=s", # tree applet area width; | ||
| 179 | "tree_base=s", # applet code directory; | ||
| 180 | ], | ||
| 181 | |||
| 182 | # there is no base option that we ignore | ||
| 183 | [], | ||
| 184 | ); | ||
| 185 | } | ||
| 186 | |||
| 187 | |||
| 188 | # provide help portions | ||
| 189 | sub help | ||
| 190 | { | ||
| 191 | # get and check parameters | ||
| 192 | (my __PACKAGE__ $me)=@_; | ||
| 193 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 194 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 195 | |||
| 196 | # to get a flexible tool, help texts are supplied in portions | ||
| 197 | { | ||
| 198 | # supply the options part | ||
| 199 | OPTIONS => { | ||
| 200 | # template files: document files | ||
| 201 | doc_template => qq(), | ||
| 202 | |||
| 203 | # template files: header contents | ||
| 204 | header_template => qq(), | ||
| 205 | header_idx_template => qq(), | ||
| 206 | header_toc_template => qq(), | ||
| 207 | |||
| 208 | # template files: body top | ||
| 209 | top_template => qq(), | ||
| 210 | top_idx_template => qq(), | ||
| 211 | top_toc_template => qq(), | ||
| 212 | |||
| 213 | # template files: body bottom | ||
| 214 | bottom_template => qq(), | ||
| 215 | bottom_idx_template => qq(), | ||
| 216 | bottom_toc_template => qq(), | ||
| 217 | |||
| 218 | # template files: navigation | ||
| 219 | nav_template => qq(), | ||
| 220 | nav_top_template => qq(), | ||
| 221 | nav_bottom_template => qq(), | ||
| 222 | |||
| 223 | # template strings | ||
| 224 | bot_left_txt => qq(), | ||
| 225 | bot_middle_txt => qq(), | ||
| 226 | bot_right_txt => qq(), | ||
| 227 | contents_header => qq(), | ||
| 228 | index_header => qq(), | ||
| 229 | label_contents => qq(), | ||
| 230 | label_index => qq(), | ||
| 231 | label_next => qq(), | ||
| 232 | label_prev => qq(), | ||
| 233 | top_left_txt => qq(), | ||
| 234 | top_middle_txt => qq(), | ||
| 235 | top_right_txt => qq(), | ||
| 236 | |||
| 237 | # logo | ||
| 238 | logo_image_filename => qq(), | ||
| 239 | |||
| 240 | # links | ||
| 241 | bootstrapaddress => qq(), | ||
| 242 | startaddress => qq(), | ||
| 243 | |||
| 244 | # link navigation | ||
| 245 | linknavigation => qq(), | ||
| 246 | |||
| 247 | # tree applet support | ||
| 248 | appletdir => qq(), | ||
| 249 | applet_dir => qq(), | ||
| 250 | appletref => qq(), | ||
| 251 | applet_ref => qq(), | ||
| 252 | |||
| 253 | tree_app_hint => qq(), | ||
| 254 | tree_app_height => qq(), | ||
| 255 | tree_app_width => qq(), | ||
| 256 | tree_base => qq(), | ||
| 257 | }, | ||
| 258 | |||
| 259 | # supply synopsis part | ||
| 260 | SYNOPSIS => <<EOS, | ||
| 261 | |||
| 262 | In this call, you are using C<Template::Traditional> templates. The Traditional template engine | ||
| 263 | is intended to allow further use of C<pp2html> styles with new Generator based converters. It | ||
| 264 | supports most of the options and keywords of C<pp2html>'s styles, plus a few additional. | ||
| 265 | |||
| 266 | Compared to other templating systems like the Template Toolkit, PerlPoint::Traditional | ||
| 267 | templates are very straightforward. Simple keywords are replaced by certain replacements. | ||
| 268 | This isn't very sophisticated, but it has the advantage to not require any additional modules | ||
| 269 | installed. If you are not satisfied by this template language, please check out templates | ||
| 270 | using other engines - search CPAN for C<PerlPoint::Template::Xyz> modules. | ||
| 271 | |||
| 272 | =head3 Template files | ||
| 273 | |||
| 274 | Following the tradition of C<pp2html>, Traditional templates expect a I<page body> to be | ||
| 275 | described by up to I<four> files which embed the page contents. The layer scheme is shown | ||
| 276 | here: | ||
| 277 | |||
| 278 | page body: <body> | ||
| 279 | |||
| 280 | top template | ||
| 281 | |||
| 282 | optional top navigation template | ||
| 283 | |||
| 284 | contents | ||
| 285 | |||
| 286 | optional bottom navigation template | ||
| 287 | |||
| 288 | bottom template | ||
| 289 | |||
| 290 | </body> | ||
| 291 | |||
| 292 | Top and bottom template files are specified by options C<-top_template> and C<-bottom_template> | ||
| 293 | for kernel pages, and C<-top_idx_template> and C<-bottom_idx_template> for index pages, and | ||
| 294 | C<-top_toc_template> and C<-bottom_toc_template> for TOC pages. | ||
| 295 | |||
| 296 | Navigation template files are specified by C<-nav_top_template> and C<-nav_bottom_template>. | ||
| 297 | These files are optional, the options can be omitted. If top and bottom navigation template | ||
| 298 | are identical, one can use C<-nav_template> to specify them both at once. | ||
| 299 | |||
| 300 | The C<<body>> and C<</body>> tags are no part of the templates, they are added automatically. | ||
| 301 | |||
| 302 | While in C<pp2html> the header of a generated page was written automatically, it now became | ||
| 303 | template driven as well. Use option C<-header_template> (or C<header_idx_template> or | ||
| 304 | C<-header_toc_template>, respectively) to specify the appropriate template. | ||
| 305 | |||
| 306 | A header template is built according to the same rules as body (part) templates, although | ||
| 307 | there are template keywords that are designed for header use only, see below. | ||
| 308 | |||
| 309 | The following scheme shows the complete layer model, including tags added automatically. Those | ||
| 310 | tags should I<not> be written to the template files. | ||
| 311 | |||
| 312 | page frame: <html> | ||
| 313 | |||
| 314 | page header: <head> | ||
| 315 | |||
| 316 | header template | ||
| 317 | |||
| 318 | </head> | ||
| 319 | |||
| 320 | page body: <body> | ||
| 321 | |||
| 322 | top template | ||
| 323 | |||
| 324 | optional top navigation template | ||
| 325 | |||
| 326 | - page contents - | ||
| 327 | |||
| 328 | optional bottom navigation template | ||
| 329 | |||
| 330 | bottom template | ||
| 331 | |||
| 332 | </body> | ||
| 333 | |||
| 334 | page frame: </html> | ||
| 335 | |||
| 336 | Additionally, one can produce I<supplementary files> such as frames. These files are templated | ||
| 337 | completely, not in parts, and get specified by C<-doc_template> for files to be produced I<once> | ||
| 338 | and C<-supplement_template> (or C<-supplement_idx_template> or C<-supplement_toc_template>, | ||
| 339 | respectively) for page specific files. The names of those generated files depend on the template | ||
| 340 | names and are composed as a sequence of the C<-prefix> value, the template file basename, a dash, | ||
| 341 | the page number. another dash and the value of option C<-suffix> for page specific files | ||
| 342 | (C<<prefix>-<tfile>-<pagenumber><suffix>>, example: C<doc-baseframe-10.html>). For document | ||
| 343 | specific files templated via C<-doc_template>, the rule is C<<prefix>-<tfile><suffix>>, example: | ||
| 344 | C<doc-frameset.html>. Each of these template options can be specified multiply, to produce as | ||
| 345 | many files as you are in need of. | ||
| 346 | |||
| 347 | Example: To produce a frameset with three frames | ||
| 348 | (top, contents, bottom), we need a frameset | ||
| 349 | file (one for all pages given we can navigate | ||
| 350 | internally), and three frame files per chapter, | ||
| 351 | which are the usual contents file plus two | ||
| 352 | extra files for the page specific top and | ||
| 353 | bottom frames. | ||
| 354 | |||
| 355 | These options will do the job: | ||
| 356 | |||
| 357 | -prefix doc -suffix .${\( lc($me->{generator}{options}{target}) )} | ||
| 358 | |||
| 359 | -doc_template frameset.tpl | ||
| 360 | -supplement_template topframe.tpl | ||
| 361 | -supplement_template bottomframe.tpl | ||
| 362 | |||
| 363 | plus the usual options to template the contents | ||
| 364 | page (which is the middle frame here). | ||
| 365 | |||
| 366 | As a result, we will get | ||
| 367 | |||
| 368 | - one file doc-frameset.${\( lc($me->{generator}{options}{target}) )} | ||
| 369 | - and three files per page: | ||
| 370 | |||
| 371 | * doc-topframe-<page>.${\( lc($me->{generator}{options}{target}) )} | ||
| 372 | * doc-<page>.${\( lc($me->{generator}{options}{target}) )} | ||
| 373 | * doc-bottomframe-<page>.${\( lc($me->{generator}{options}{target}) )} | ||
| 374 | |||
| 375 | Knowing how the filenames are build, all files can be interlinked with ease. | ||
| 376 | |||
| 377 | =head3 Keywords | ||
| 378 | |||
| 379 | The keywords supported in Traditional templates are listed in the following. | ||
| 380 | |||
| 381 | =over 4 | ||
| 382 | |||
| 383 | =item BOT_LEFT_TXT | ||
| 384 | |||
| 385 | Inserts the text specified by option C<-bot_left_txt>. | ||
| 386 | |||
| 387 | =item BOT_MIDDLE_TXT | ||
| 388 | |||
| 389 | Inserts the text specified by option C<-bot_middle_txt>. | ||
| 390 | |||
| 391 | =item BOT_RIGHT_TXT | ||
| 392 | |||
| 393 | Inserts the text specified by option C<-bot_right_txt>. | ||
| 394 | |||
| 395 | =item BOOTSTRAP_ADDRESS | ||
| 396 | |||
| 397 | Inserts the URL specified by option C<-boostrapaddress>, pointing to the absolute start URL | ||
| 398 | (a page that does not need to be generated, by the way). | ||
| 399 | |||
| 400 | =item DATE(<format>) | ||
| 401 | |||
| 402 | This is a I<function> and will be replaced by the current data and time, formatted via | ||
| 403 | C<POSIX::strftime()>. The <format> is required in C<POSIX::strftime()> syntax. | ||
| 404 | |||
| 405 | Example: DATE(%c) | ||
| 406 | |||
| 407 | =item DOCAUTHOR | ||
| 408 | |||
| 409 | The I<document> author, as specified by option C<-docauthor>. | ||
| 410 | |||
| 411 | =item DOCDATE | ||
| 412 | |||
| 413 | The document date/time string, as configured by option C<-docdate>. | ||
| 414 | |||
| 415 | =item DOCSUBTITLE | ||
| 416 | |||
| 417 | The I<document> subtitle, as specified by option C<-docsubtitle>. | ||
| 418 | |||
| 419 | =item DOCTITLE | ||
| 420 | |||
| 421 | The I<document> title, as specified by option C<-doctitle>. | ||
| 422 | |||
| 423 | =item LABEL_CONTENTS | ||
| 424 | |||
| 425 | Inserts the text specified by option C<-label_contents>. | ||
| 426 | |||
| 427 | =item LABEL_INDEX | ||
| 428 | |||
| 429 | Inserts the text specified by option C<-label_index>. | ||
| 430 | |||
| 431 | =item LABEL_NEXT | ||
| 432 | |||
| 433 | Inserts the text specified by option C<-label_next>. | ||
| 434 | |||
| 435 | =item LABEL_PREV | ||
| 436 | |||
| 437 | Inserts the text specified by option C<-label_prev>. | ||
| 438 | |||
| 439 | =item LOGO_IMAGE_FILENAME | ||
| 440 | |||
| 441 | =item OPT(<option>, <text>) | ||
| 442 | |||
| 443 | Inserts <text> if <option> is set. The <text> can contain further keywords, except for | ||
| 444 | nested C<OPT()> calls. | ||
| 445 | |||
| 446 | For reasons of parsing, make sure the closing paren is the last paren in the template | ||
| 447 | line, as the function consumes everything till there. | ||
| 448 | |||
| 449 | Example: OPT(flavicon, <p>These pages use flavicons.</p>) | ||
| 450 | |||
| 451 | =item PAGE_CONTENTS | ||
| 452 | |||
| 453 | The page number of the TOC page. | ||
| 454 | |||
| 455 | =item PAGE_FIRST | ||
| 456 | |||
| 457 | The page number of the first page. | ||
| 458 | |||
| 459 | =item PAGE_HERE | ||
| 460 | |||
| 461 | The page number of the current page. | ||
| 462 | |||
| 463 | =item PAGE_INDEX | ||
| 464 | |||
| 465 | The page number of the index page, if any. | ||
| 466 | |||
| 467 | =item PAGE_LAST | ||
| 468 | |||
| 469 | The page number of the last page. | ||
| 470 | |||
| 471 | =item PAGE_NEXT | ||
| 472 | |||
| 473 | The page number of the next page, if any. | ||
| 474 | |||
| 475 | =item PAGE_PATH | ||
| 476 | |||
| 477 | This inserts the "path" of the current chapter, which is a sequence of (short) chapter titles | ||
| 478 | (being links to the chapters), leading from root to the current page. This is useful for | ||
| 479 | navigation, to allow readers quick jumps to higher level base chapters. | ||
| 480 | |||
| 481 | The start URL specified by C<-bootstrapaddress> always starts the path. Levels are delimited by | ||
| 482 | slashes. | ||
| 483 | |||
| 484 | Example: If in the hierarchy of chapters | ||
| 485 | |||
| 486 | 1. Root Level | ||
| 487 | |||
| 488 | 1.1. Sublevel | ||
| 489 | |||
| 490 | 1.2. More about this | ||
| 491 | |||
| 492 | 1.2.1. Example | ||
| 493 | |||
| 494 | the PAGE_PATH keyword should be replaced on every page, | ||
| 495 | the result would be | ||
| 496 | |||
| 497 | for 1.: Start URL | ||
| 498 | |||
| 499 | for 1.1.: Start URL / Root Level | ||
| 500 | |||
| 501 | for 1.2.: Start URL / Root Level | ||
| 502 | |||
| 503 | for 1.2.1.: Start URL / Root level / More about this | ||
| 504 | |||
| 505 | =item PAGE_PREV | ||
| 506 | |||
| 507 | The page number of the previous page, if any. | ||
| 508 | |||
| 509 | =item PAGE_UP | ||
| 510 | |||
| 511 | The page number of the parent page. | ||
| 512 | |||
| 513 | =item REF(E<lt>separatorE<gt>E<lt>whitespace(s)E<gt>E<lt>address> E<lt>separatorE<gt> E<lt>textE<gt>) | ||
| 514 | |||
| 515 | A link to a document anchor, described by E<lt>addressE<gt>. Addresses are specified the same | ||
| 516 | way as in the C<name> option of C<\REF> tags, see there for details. The E<lt>textE<gt> | ||
| 517 | is used to set up the link text. Address and text are delimited by a string defined | ||
| 518 | as E<lt>separatorE<gt>. The whitespace after the separator definition is I<mandatory>, | ||
| 519 | more whitespaces can be used at your option. | ||
| 520 | |||
| 521 | Examples: | ||
| 522 | |||
| 523 | REF(, An interesting chapter, Chapter) | ||
| 524 | |||
| 525 | REF(--- Overview | perl, parl and PAR --- A PAR intro) | ||
| 526 | |||
| 527 | Closing parens within addresses or texts have to be preceeded by a backslash. | ||
| 528 | |||
| 529 | REF(# Tools (par and parl\) # Tools) | ||
| 530 | |||
| 531 | =item START_ADDRESS | ||
| 532 | |||
| 533 | Inserts the URL specified by option C<-startaddress>, pointing to the very first page. | ||
| 534 | |||
| 535 | =item TREE_APPLET_TOC | ||
| 536 | |||
| 537 | Inserts code for the free Java navigation applet traditionally provided with C<pp2html>. | ||
| 538 | Different to C<pp2html>, the "Traditional" template engine does not generate applet TOC | ||
| 539 | pages on its own, but it supports styles that build such pages. To do so, just use this | ||
| 540 | wildcard in a TOC template specified by C<-top_toc_template> or C<-bottom_toc_template>. | ||
| 541 | |||
| 542 | If the wildcard is used, the template engine copies all necessary Java files into the | ||
| 543 | directory specified by option C<-appletdir>. Other related options are C<-appletdir> | ||
| 544 | (or C<-applet_dir>), C<-appletref> (or C<-applet_ref>), C<-tree_app_hint>, C<-tree_app_height>, | ||
| 545 | C<-tree_app_width> and C<-tree_base>. | ||
| 546 | |||
| 547 | |||
| 548 | =item TXT_CONTENTS | ||
| 549 | |||
| 550 | The title of the TOC page. | ||
| 551 | |||
| 552 | =item TXT_FIRST | ||
| 553 | |||
| 554 | The title of the first page. | ||
| 555 | |||
| 556 | =item TXT_HERE | ||
| 557 | |||
| 558 | The title of the current page. | ||
| 559 | |||
| 560 | =item TXT_INDEX | ||
| 561 | |||
| 562 | The title of the index page, if any. | ||
| 563 | |||
| 564 | =item TXT_LAST | ||
| 565 | |||
| 566 | The title of the last page. | ||
| 567 | |||
| 568 | =item TXT_NEXT | ||
| 569 | |||
| 570 | The title of the next page, if any. | ||
| 571 | |||
| 572 | =item TXT_PREV | ||
| 573 | |||
| 574 | The title of the previous page, if any. | ||
| 575 | |||
| 576 | =item TXT_UP | ||
| 577 | |||
| 578 | The title of the parent page. | ||
| 579 | |||
| 580 | =item TOP_LEFT_TXT | ||
| 581 | |||
| 582 | Inserts the text specified by option C<-top_left_txt>. | ||
| 583 | |||
| 584 | =item TOP_MIDDLE_TXT | ||
| 585 | |||
| 586 | Inserts the text specified by option C<-top_middle_txt>. | ||
| 587 | |||
| 588 | =item TOP_RIGHT_TXT | ||
| 589 | |||
| 590 | =item TITLE | ||
| 591 | |||
| 592 | The I<page> title (chapter headline). | ||
| 593 | |||
| 594 | =item URL_CONTENTS | ||
| 595 | |||
| 596 | The URL of the TOC page. | ||
| 597 | |||
| 598 | =item URL_FIRST | ||
| 599 | |||
| 600 | The URL of the first page. | ||
| 601 | |||
| 602 | =item URL_HERE | ||
| 603 | |||
| 604 | The URL of the current page. | ||
| 605 | |||
| 606 | =item URL_INDEX | ||
| 607 | |||
| 608 | The URL of the index page, if any. | ||
| 609 | |||
| 610 | =item URL_LAST | ||
| 611 | |||
| 612 | The URL of the last page. | ||
| 613 | |||
| 614 | =item URL_NEXT | ||
| 615 | |||
| 616 | The URL of the next page, if any. | ||
| 617 | |||
| 618 | =item URL_PREV | ||
| 619 | |||
| 620 | The URL of the previous page, if any. | ||
| 621 | |||
| 622 | =item URL_UP | ||
| 623 | |||
| 624 | The URL of the parent page. | ||
| 625 | |||
| 626 | =item VAR(<var>) or VAR_AT_FINISH(<var>) | ||
| 627 | |||
| 628 | Inserts the value of the PerlPoint variable <var>, with the value available at the I<end> | ||
| 629 | of the chapter. | ||
| 630 | |||
| 631 | Example: VAR(language) | ||
| 632 | |||
| 633 | =item VAR_AT_BEGIN(<var>) | ||
| 634 | |||
| 635 | Inserts the value of the PerlPoint variable <var>, with the value available at the I<beginning> | ||
| 636 | of the chapter. | ||
| 637 | |||
| 638 | Example: VAR_AT_BEGIN(language) | ||
| 639 | |||
| 640 | =item CSS_LINKTAGS | ||
| 641 | |||
| 642 | Inserts tags to load CSS files specified by option C<-css>. The stylesheet specified first | ||
| 643 | will be made the main stylesheet, while all subsequently specified sheets will be included | ||
| 644 | as alternatives, in the order they were declared. | ||
| 645 | |||
| 646 | According to the specs, this keyword should be used in header templates only. (This will not | ||
| 647 | be checked by the template engine.) | ||
| 648 | |||
| 649 | =item DOC_METATAGS | ||
| 650 | |||
| 651 | According to the specs, this keyword should be used in header templates only. (This will not | ||
| 652 | be checked by the template engine.) | ||
| 653 | |||
| 654 | =item FAVICON_LINKTAG | ||
| 655 | |||
| 656 | Inserts a favicon link tag referring to the icon specified by option C<-favicon>. If the | ||
| 657 | option was omitted, the keyword will be replaced by an empty string. | ||
| 658 | |||
| 659 | For details about favicons, please see the description of C<-favicon>. | ||
| 660 | |||
| 661 | According to the specs, this keyword should be used in header templates only. (This will not | ||
| 662 | be checked by the template engine.) | ||
| 663 | |||
| 664 | =item LINK_NAVIGATION | ||
| 665 | |||
| 666 | Inserts navigation link tags as specified by the W3C (C<<link rel="start" ...>> etc.). Most | ||
| 667 | modern browsers translate them into navigation buttons to the first, previous, next etc. page. | ||
| 668 | |||
| 669 | According to the specs, this keyword should be used in header templates only. (This will not | ||
| 670 | be checked by the template engine.) | ||
| 671 | |||
| 672 | =item PAGE | ||
| 673 | |||
| 674 | The number of the current page. Counting starts with 1. | ||
| 675 | |||
| 676 | =item PAGE_CNT | ||
| 677 | |||
| 678 | The number of chapters (pages) in the document. | ||
| 679 | |||
| 680 | Example: to display "page x of y", use | ||
| 681 | |||
| 682 | PAGE/PAGE_CNT | ||
| 683 | |||
| 684 | =item TITLE | ||
| 685 | |||
| 686 | This will insert the document title, as specified by option C<-title>. | ||
| 687 | |||
| 688 | =back | ||
| 689 | |||
| 690 | =cut | ||
| 691 | |||
| 692 | EOS | ||
| 693 | } | ||
| 694 | } | ||
| 695 | |||
| 696 | |||
| 697 | |||
| 698 | # bootstrap | ||
| 699 | sub bootstrap | ||
| 700 | { | ||
| 701 | # get and check parameters | ||
| 702 | (my __PACKAGE__ $me)=@_; | ||
| 703 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 704 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 705 | |||
| 706 | # don't forget the base method | ||
| 707 | $me->SUPER::bootstrap(); | ||
| 708 | |||
| 709 | # copy CSS and JavaScript files, if necessary | ||
| 710 | my $dir=join('/', $me->{generator}{cfg}{setup}{stylepath}, $me->options->{style}, 'templates'); | ||
| 711 | foreach my $file (<$dir/*.css>, <$dir/*.js>) | ||
| 712 | { | ||
| 713 | # get basename | ||
| 714 | my $basename=basename($file); | ||
| 715 | |||
| 716 | # copy file, if necessary | ||
| 717 | if ( | ||
| 718 | not -e "$me->{generator}{options}{targetdir}/$basename" | ||
| 719 | or -M "$me->{generator}{options}{targetdir}/$basename" > -M $file | ||
| 720 | ) | ||
| 721 | { | ||
| 722 | warn "[Info] Copying ", $file=~/\.css$/i ? 'CSS' : 'JavaScript', " file $file to target directory $me->{generator}{options}{targetdir}.\n"; | ||
| 723 | copy($file, $me->{generator}{options}{targetdir}) or die "[Fatal] Could not copy $file to $me->{generator}{options}{targetdir}.\n"; | ||
| 724 | } | ||
| 725 | } | ||
| 726 | |||
| 727 | # configure applet options as necessary | ||
| 728 | $me->{options}{tree_app_hint}='Please, activate Java.' unless exists $me->{options}{tree_app_hint}; | ||
| 729 | $me->{options}{tree_app_height}=400 unless exists $me->{options}{tree_app_height}; | ||
| 730 | $me->{options}{tree_app_width}=200 unless exists $me->{options}{tree_app_width}; | ||
| 731 | $me->{options}{appletdir}=$me->{options}{targetdir} unless exists $me->{options}{appletdir}; | ||
| 732 | |||
| 733 | if (not exists $me->{options}{appletref}) | ||
| 734 | { | ||
| 735 | if ($me->{options}{appletdir} eq $me->{options}{targetdir}) | ||
| 736 | {$me->{options}{appletref}='.';} | ||
| 737 | else | ||
| 738 | { | ||
| 739 | if ($me->{options}{appletdir}=~m(^/)) | ||
| 740 | { | ||
| 741 | # we got an absolute path, use it | ||
| 742 | $me->{options}{appletref}=$me->{options}{appletdir}; | ||
| 743 | } | ||
| 744 | else | ||
| 745 | { | ||
| 746 | # we got a relative path, absolutify it and use the result | ||
| 747 | my ($base, $path, $type)=fileparse($me->{options}{appletdir}); | ||
| 748 | $me->{options}{appletref}=join('/', abs_path($path), basename($me->{options}{appletdir})); | ||
| 749 | } | ||
| 750 | } | ||
| 751 | } | ||
| 752 | |||
| 753 | $me->{options}{tree_base}=$me->{options}{appletref} unless exists $me->{options}{tree_base}; | ||
| 754 | |||
| 755 | # make applet target directory, if necessary | ||
| 756 | if (exists $me->{options}{appletdir} and not -d $me->{options}{appletdir}) | ||
| 757 | { | ||
| 758 | warn "[Info] Making tree applet directory $me->{options}{appletdir}.\n" unless exists $me->{options}{noinfo}; | ||
| 759 | mkpath($me->{options}{appletdir}); | ||
| 760 | } | ||
| 761 | } | ||
| 762 | |||
| 763 | |||
| 764 | # check usage | ||
| 765 | sub checkUsage | ||
| 766 | { | ||
| 767 | # get and check parameters | ||
| 768 | (my __PACKAGE__ $me)=@_; | ||
| 769 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 770 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 771 | |||
| 772 | # don't forget the base class | ||
| 773 | $me->SUPER::checkUsage; | ||
| 774 | |||
| 775 | # get options | ||
| 776 | my $options=$me->options; | ||
| 777 | |||
| 778 | # check mandatory options | ||
| 779 | foreach (qw(header_template top_template bottom_template)) | ||
| 780 | {die qq([Fatal] "Traditional" templates require option -$_.\n) unless exists $options->{$_};} | ||
| 781 | |||
| 782 | # check mandatory files | ||
| 783 | foreach (qw(header_template top_template bottom_template)) | ||
| 784 | { | ||
| 785 | my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$options->{$_}"; | ||
| 786 | die qq([Fatal] Missing "Traditional" "-$_" template file "$options->{$_}".\n) unless -e $filename; | ||
| 787 | } | ||
| 788 | |||
| 789 | # check files belonging to optional options | ||
| 790 | foreach ( | ||
| 791 | qw( | ||
| 792 | doc_template | ||
| 793 | |||
| 794 | header_idx_template | ||
| 795 | header_toc_template | ||
| 796 | |||
| 797 | top_idx_template | ||
| 798 | top_toc_template | ||
| 799 | |||
| 800 | bottom_idx_template | ||
| 801 | bottom_toc_template | ||
| 802 | |||
| 803 | nav_template | ||
| 804 | nav_idx_template | ||
| 805 | nav_toc_template | ||
| 806 | |||
| 807 | supplement_template | ||
| 808 | supplement_idx_template | ||
| 809 | supplement_toc_template | ||
| 810 | ) | ||
| 811 | ) | ||
| 812 | { | ||
| 813 | # skip check if option unused | ||
| 814 | next unless exists $options->{$_}; | ||
| 815 | |||
| 816 | # template options can specify one or multiple files | ||
| 817 | unless (ref $options->{$_}) | ||
| 818 | { | ||
| 819 | my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$options->{$_}"; | ||
| 820 | die qq([Fatal] Missing "Traditional" "-$_" template file "$options->{$_}".\n) unless -e $filename; | ||
| 821 | } | ||
| 822 | else | ||
| 823 | { | ||
| 824 | # process each file | ||
| 825 | foreach my $template (@{$options->{$_}}) | ||
| 826 | { | ||
| 827 | my $filename="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates/$template"; | ||
| 828 | die qq([Fatal] Missing "Traditional" "-$_" template file "$template".\n) unless -e $filename; | ||
| 829 | } | ||
| 830 | } | ||
| 831 | } | ||
| 832 | |||
| 833 | # flag success | ||
| 834 | 1; | ||
| 835 | } | ||
| 836 | |||
| 837 | |||
| 838 | # the transformator | ||
| 839 | sub transform | ||
| 840 | { | ||
| 841 | # get and check parameters | ||
| 842 | ((my __PACKAGE__ $me), my %params)=@_; | ||
| 843 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 844 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 845 | confess "[BUG] Missing action parameter.\n" unless exists $params{action} and defined $params{action}; | ||
| 846 | unless ( | ||
| 847 | $params{action}==TEMPLATE_ACTION_DOC | ||
| 848 | or $params{action}==TEMPLATE_ACTION_TOC | ||
| 849 | or $params{action}==TEMPLATE_ACTION_INDEX | ||
| 850 | ) | ||
| 851 | { | ||
| 852 | confess "[BUG] Missing page number parameter.\n" unless exists $params{page} and defined $params{page}; | ||
| 853 | confess "[BUG] Missing data parameter.\n" unless exists $params{data} and defined $params{data}; | ||
| 854 | } | ||
| 855 | |||
| 856 | # declarations | ||
| 857 | my ($result)=(''); | ||
| 858 | |||
| 859 | # get options | ||
| 860 | my $options=$me->options; | ||
| 861 | |||
| 862 | # build template directory path | ||
| 863 | my $tdir="$me->{generator}{cfg}{setup}{stylepath}/$options->{style}/templates"; | ||
| 864 | |||
| 865 | # transform source data into a string, if required | ||
| 866 | |||
| 867 | # act action dependent: generate document pages | ||
| 868 | $params{action}==TEMPLATE_ACTION_DOC and do | ||
| 869 | { | ||
| 870 | # first look if there are supplements to process | ||
| 871 | if (exists $options->{doc_template}) | ||
| 872 | { | ||
| 873 | # process each supplement | ||
| 874 | foreach my $template (@{$options->{doc_template}}) | ||
| 875 | { | ||
| 876 | # process template (use first page number) | ||
| 877 | my $string=$me->_processTemplate("$tdir/$template", 1); | ||
| 878 | |||
| 879 | # build file name | ||
| 880 | my $filename=join('', "$options->{targetdir}/$options->{prefix}-", (fileparse($template, qr(\.[^.]+)))[0], $options->{suffix}); | ||
| 881 | |||
| 882 | # write file | ||
| 883 | open(SUPPFILE, ">$filename") or die qq([Fatal] Could not open output file "$filename": $!.\n); | ||
| 884 | print SUPPFILE $string; | ||
| 885 | close(SUPPFILE); | ||
| 886 | } | ||
| 887 | } | ||
| 888 | }; | ||
| 889 | |||
| 890 | # act action dependent: generate a (toc) page | ||
| 891 | ($params{action}==TEMPLATE_ACTION_PAGE or $params{action}==TEMPLATE_ACTION_TOC) and do | ||
| 892 | { | ||
| 893 | # anything to do? | ||
| 894 | return if $params{action}==TEMPLATE_ACTION_TOC and not exists $options->{header_toc_template}; | ||
| 895 | my $toc=$params{action}==TEMPLATE_ACTION_TOC; | ||
| 896 | |||
| 897 | # start page | ||
| 898 | $result.="\n\n<html>\n\n"; | ||
| 899 | |||
| 900 | # begin header | ||
| 901 | $result.="\n\n<head>\n\n"; | ||
| 902 | |||
| 903 | # header contents: this was added to the traditional list of template files | ||
| 904 | $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'header_toc_template' : 'header_template'}), $toc ? 1 : $params{page}); | ||
| 905 | |||
| 906 | # complete header | ||
| 907 | $result.="\n\n</head>\n\n"; | ||
| 908 | |||
| 909 | # begin body | ||
| 910 | $result.="\n\n<body>\n\n"; | ||
| 911 | |||
| 912 | # now the body contents: start with top part | ||
| 913 | $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'top_toc_template' : 'top_template'}), $toc ? 1 : $params{page}); | ||
| 914 | |||
| 915 | # add navigation, if necessary | ||
| 916 | $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'nav_toc_template' : 'nav_template'}), $toc ? 1 : $params{page}) | ||
| 917 | if exists $options->{$toc ? 'nav_toc_template' : 'nav_template'}; | ||
| 918 | |||
| 919 | # include data (for TOCs, make sure not to add a standard TOC if the tree applet is used | ||
| 920 | # - this should be more generic in case users use other methods ...) | ||
| 921 | $result.=$toc ? $result=~/<applet code="TreeApp\.class" codebase=/ ? '' : $me->_toc() : $params{data}; | ||
| 922 | |||
| 923 | # add bottom navigation, if necessary | ||
| 924 | $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'nav_toc_template' : 'nav_template'}), $toc ? 1 : $params{page}) | ||
| 925 | if exists $options->{$toc ? 'nav_toc_template' : 'nav_template'}; | ||
| 926 | |||
| 927 | # finally, add the bottom part | ||
| 928 | $result.=$me->_processTemplate(join('/', $tdir, $options->{$toc ? 'bottom_toc_template' : 'bottom_template'}), $toc ? 1 : $params{page}); | ||
| 929 | |||
| 930 | # close the body | ||
| 931 | $result.="\n\n</body>\n\n"; | ||
| 932 | |||
| 933 | # and complete the page | ||
| 934 | $result.="\n\n</html>\n\n"; | ||
| 935 | }; | ||
| 936 | |||
| 937 | |||
| 938 | # act action dependent: generate supplements | ||
| 939 | $params{action}==TEMPLATE_ACTION_PAGE_SUPPLEMENTS and do | ||
| 940 | { | ||
| 941 | # first look if there are supplements to process | ||
| 942 | if (exists $options->{supplement_template}) | ||
| 943 | { | ||
| 944 | # process each supplement | ||
| 945 | foreach my $template (@{$options->{supplement_template}}) | ||
| 946 | { | ||
| 947 | # process template | ||
| 948 | my $string=$me->_processTemplate("$tdir/$template", $params{page}); | ||
| 949 | |||
| 950 | # build file name | ||
| 951 | my $filename=join('', "$options->{targetdir}/$options->{prefix}-", (fileparse($template, qr(\.[^.]+)))[0], "-$params{page}$options->{suffix}"); | ||
| 952 | warn "= PAGE SUPPLEMENT =====> $filename\n"; | ||
| 953 | |||
| 954 | # write file | ||
| 955 | open(SUPPFILE, ">$filename") or die qq([Fatal] Could not open output file "$filename": $!.\n); | ||
| 956 | print SUPPFILE $string; | ||
| 957 | close(SUPPFILE); | ||
| 958 | } | ||
| 959 | } | ||
| 960 | }; | ||
| 961 | |||
| 962 | # retransform string result into a special data format, if required | ||
| 963 | |||
| 964 | # supply result | ||
| 965 | $result; | ||
| 966 | } | ||
| 967 | |||
| 968 | |||
| 969 | |||
| 970 | # helper functions ########################################################## | ||
| 971 | |||
| 972 | # process a template | ||
| 973 | sub _processTemplate | ||
| 974 | { | ||
| 975 | # get and check parameters | ||
| 976 | ((my __PACKAGE__ $me), my ($file, $page))=@_; | ||
| 977 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 978 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 979 | confess "[BUG] Missing template file parameter.\n" unless $file; | ||
| 980 | confess "[BUG] Missing page data parameter.\n" unless $page; | ||
| 981 | |||
| 982 | # declare variables | ||
| 983 | my (@result); | ||
| 984 | |||
| 985 | # common preprocessing | ||
| 986 | my $td=$me->preprocessData($page); | ||
| 987 | |||
| 988 | # get options | ||
| 989 | my $options=$me->options; | ||
| 990 | |||
| 991 | # stylesheet links | ||
| 992 | my $cssLinkTags=join('', exists $options->{css} ? map | ||
| 993 | { | ||
| 994 | # extract title and filename | ||
| 995 | my ($file, $title)=split(':', $options->{css}[$_], 2); | ||
| 996 | $title="unnamed $_" if $_ and not $title; | ||
| 997 | |||
| 998 | # add css links | ||
| 999 | join('', | ||
| 1000 | qq(<link href="$file"), | ||
| 1001 | $_ ? qq( title="$title") : '', | ||
| 1002 | ' rel="', $_<2 ? 'stylesheet' : 'alternate stylesheet', '"', | ||
| 1003 | qq( type="text/css"), | ||
| 1004 | qq( />\n), | ||
| 1005 | ); | ||
| 1006 | } 0..$#{$options->{css}} : (), | ||
| 1007 | ); | ||
| 1008 | |||
| 1009 | # add favicon link, if necessary | ||
| 1010 | my $faviconLinkTag=exists $me->{options}{favicon} ? qq(<link href="$me->{options}{favicon}" rel="SHORTCUT ICON" type="image/ico" />\n) : ''; | ||
| 1011 | |||
| 1012 | # the "doc..." options are reserved for further data ... stored in meta tags | ||
| 1013 | my $docMetaTags=''; | ||
| 1014 | for (sort grep((/^doc/ and not /^doc(_|title)/), keys %$options)) | ||
| 1015 | { | ||
| 1016 | /^doc(.+)$/; | ||
| 1017 | my $tag=$me->{generator}->elementName("_$1"); | ||
| 1018 | $docMetaTags.=join('', qq( <meta name="$tag" content="$options->{$_}" />\n)) if exists $options->{$_}; | ||
| 1019 | }; | ||
| 1020 | |||
| 1021 | # add more meta tags, if necessary | ||
| 1022 | $docMetaTags.=qq( <meta name="ROBOTS" content="NOINDEX, NOFOLLOW" />\n) if exists $options->{norobots}; | ||
| 1023 | $docMetaTags.=qq( <meta name="MSSmartTagsPreventParsing" content="true" />\n) if exists $options->{nosmarttags}; | ||
| 1024 | |||
| 1025 | # prepare <link> navigation if required | ||
| 1026 | my $linkNavigation=''; | ||
| 1027 | if (exists $options->{linknavigation}) | ||
| 1028 | { | ||
| 1029 | # activate available elements | ||
| 1030 | $linkNavigation.=qq( <link rel="start" href="$td->{fFile}" />\n) if $td->{fFile}; | ||
| 1031 | $linkNavigation.=qq( <link rel="prev" href="$td->{pFile}" />\n) if $td->{pFile}; | ||
| 1032 | $linkNavigation.=qq( <link rel="next" href="$td->{nFile}" />\n) if $td->{nFile}; | ||
| 1033 | $linkNavigation.=qq( <link rel="up" href="$td->{uFile}" />\n) if $td->{uFile}; | ||
| 1034 | $linkNavigation.=qq( <link rel="last" href="$td->{lFile}" />\n) if $td->{lFile}; | ||
| 1035 | |||
| 1036 | # the contents link is always available | ||
| 1037 | $linkNavigation.=qq( <link rel="contents" href="$td->{tocFile}" />\n); | ||
| 1038 | |||
| 1039 | # add the index link, if possible | ||
| 1040 | $linkNavigation.=qq( <link rel="index" href="$td->{indexFile}" />\n) if $td->{indexFile} and not exists $options->{no_index}; | ||
| 1041 | } | ||
| 1042 | |||
| 1043 | # prepare the linked page path | ||
| 1044 | my $cPath=join(' / ', map {join('', qq(<a href="$_->[0]">$_->[1]</a>));} @{$td->{cPath}}); | ||
| 1045 | |||
| 1046 | # ok, open template | ||
| 1047 | open(TPL, $file) or die "[Fatal] Can't open template $file: $!\n"; | ||
| 1048 | |||
| 1049 | # replace placeholders | ||
| 1050 | while (<TPL>) | ||
| 1051 | { | ||
| 1052 | # optional parts (evaluate them first, to allow placeholders in substitutions) | ||
| 1053 | s/OPT\((.+?),\s*(.+)\s*\)/exists $options->{$1} ? $2 : ''/ge; | ||
| 1054 | |||
| 1055 | # process static placeholders | ||
| 1056 | s/\bTITLE\b/$td->{title}/g; | ||
| 1057 | s/\bCSS_LINKTAGS\b/$cssLinkTags/g; | ||
| 1058 | s/\bFAVICON_LINKTAG\b/$faviconLinkTag/g; | ||
| 1059 | s/\bDOC_METATAGS\b/$docMetaTags/g; | ||
| 1060 | s/\bLINK_NAVIGATION\b/$linkNavigation/g; | ||
| 1061 | |||
| 1062 | s/URL_FIRST/$td->{fFile}/g; | ||
| 1063 | s/TXT_FIRST/$td->{fText}/g; | ||
| 1064 | s/PAGE_FIRST/$td->{fNumber}/g; | ||
| 1065 | |||
| 1066 | s/URL_HERE/$td->{cFile}/g; | ||
| 1067 | s/TXT_HERE/$td->{cText}/g; | ||
| 1068 | s/PAGE_HERE/$td->{cNumber}/g; | ||
| 1069 | |||
| 1070 | s/URL_LAST/$td->{lFile}/g; | ||
| 1071 | s/TXT_LAST/$td->{lText}/g; | ||
| 1072 | s/PAGE_LAST/$td->{lNumber}/g; | ||
| 1073 | |||
| 1074 | s/URL_PREV/$td->{pFile}/g; | ||
| 1075 | s/TXT_PREV/$td->{pText}/g; | ||
| 1076 | s/PAGE_PREV/$td->{pNumber}/g; | ||
| 1077 | |||
| 1078 | s/URL_NEXT/$td->{nFile}/g; | ||
| 1079 | s/TXT_NEXT/$td->{nText}/g; | ||
| 1080 | s/PAGE_NEXT/$td->{nNumber}/g; | ||
| 1081 | |||
| 1082 | s/URL_UP/$td->{uFile}/g; | ||
| 1083 | s/TXT_UP/$td->{uText}/g; | ||
| 1084 | s/PAGE_UP/$td->{uNumber}/g; | ||
| 1085 | |||
| 1086 | # what's this meant to be??? | ||
| 1087 | # s/<[\s\w="]*URL_DOWN[\s"]*?>/$url_down/g; | ||
| 1088 | # s/TXT_DOWN/$txt_down/g; | ||
| 1089 | |||
| 1090 | # addresses of specific pages | ||
| 1091 | s/URL_CONTENTS/$td->{tocFile}/g; | ||
| 1092 | s/URL_INDEX/$td->{indexFile}/g; | ||
| 1093 | |||
| 1094 | # page data | ||
| 1095 | s/\bPAGE_CNT\b/$td->{pageNr}/g; | ||
| 1096 | s/\bPAGE\b/$page/g; | ||
| 1097 | s/PAGE_PATH/$cPath/g; | ||
| 1098 | |||
| 1099 | # various straight forward keyword/option translations | ||
| 1100 | s/TXT_CONTENTS/exists $options->{contents_header} ? $options->{contents_header} : ''/geo; | ||
| 1101 | s/TXT_INDEX/exists $options->{index_header} ? $options->{index_header} : ''/geo; | ||
| 1102 | s/BOOTSTRAP_ADDRESS/exists $options->{boostrapaddress} ? $options->{boostrapaddress} : ''/geo; | ||
| 1103 | s/START_ADDRESS/exists $options->{startaddress} ? $options->{startaddress} : ''/geo; | ||
| 1104 | foreach my $keyword (qw( | ||
| 1105 | BOT_LEFT_TXT | ||
| 1106 | BOT_MIDDLE_TXT | ||
| 1107 | BOT_RIGHT_TXT | ||
| 1108 | DOCAUTHOR | ||
| 1109 | DOCDATE | ||
| 1110 | DOCSUBTITLE | ||
| 1111 | DOCTITLE | ||
| 1112 | LABEL_CONTENTS | ||
| 1113 | LABEL_INDEX | ||
| 1114 | LABEL_NEXT | ||
| 1115 | LABEL_PREV | ||
| 1116 | LOGO_IMAGE_FILENAME | ||
| 1117 | PREFIX | ||
| 1118 | SUFFIX | ||
| 1119 | TOP_LEFT_TXT | ||
| 1120 | TOP_MIDDLE_TXT | ||
| 1121 | TOP_RIGHT_TXT | ||
| 1122 | ) | ||
| 1123 | ) | ||
| 1124 | {s/$keyword/exists $options->{lc($keyword)} ? $options->{lc($keyword)} : ''/ge;} | ||
| 1125 | |||
| 1126 | # "functions" | ||
| 1127 | s/DATE\((.+?)\)/strftime($1, localtime)/ge; | ||
| 1128 | s/REF\((\S+)\s+(.+)(?:\s*\1\s*(.+))(?<!\\)\)/$me->{generator}->buildAnchorLink($2, defined($3) ? $3 : ())/ge; | ||
| 1129 | |||
| 1130 | # variables | ||
| 1131 | s/VAR(_AT_FINISH)?\((.+?)\)/exists $td->{cVars}{$2} ? $td->{cVars}{$2} : ''/ge; | ||
| 1132 | s/VAR_AT_BEGIN\((.+?)\)/exists $td->{pVars}{$1} ? $td->{pVars}{$1} : ''/ge; | ||
| 1133 | |||
| 1134 | # special: tree applet index | ||
| 1135 | if (/TREE_APPLET_TOC/) | ||
| 1136 | { | ||
| 1137 | # copy applet classes, if necessary | ||
| 1138 | my $appletSrcDir="$me->{generator}{cfg}{setup}{stylepath}/$me->{generator}{options}{style}/templates/applet_src"; | ||
| 1139 | die("[Fatal] No applet source directory in ", dirname($appletSrcDir), ".\n") unless -d $appletSrcDir; | ||
| 1140 | foreach my $appletfile (sort <$appletSrcDir/*.class>) | ||
| 1141 | { | ||
| 1142 | # get image basename | ||
| 1143 | my $basename=basename($appletfile); | ||
| 1144 | |||
| 1145 | # copy image, if necessary | ||
| 1146 | if ( | ||
| 1147 | exists $me->{options}{appletdir} | ||
| 1148 | and ( | ||
| 1149 | not -e "$me->{options}{appletdir}/$basename" | ||
| 1150 | or -M "$me->{options}{appletdir}/$basename" > -M $appletfile | ||
| 1151 | ) | ||
| 1152 | ) | ||
| 1153 | { | ||
| 1154 | # inform user, unless suppressed | ||
| 1155 | warn qq([Info] Copying tree applet file $appletfile to $me->{options}{appletdir}.\n) unless exists $me->{options}{noinfo}; | ||
| 1156 | |||
| 1157 | # perform action | ||
| 1158 | copy($appletfile, $me->{options}{appletdir}); | ||
| 1159 | } | ||
| 1160 | } | ||
| 1161 | |||
| 1162 | # begin the applet code string | ||
| 1163 | my $applet=<<EOA; | ||
| 1164 | |||
| 1165 | <applet code="TreeApp.class" codebase="$options->{tree_base}" alt="$options->{tree_app_hint}" name="Tree" width="$options->{tree_app_width}" height="$options->{tree_app_height}"> | ||
| 1166 | <param name=bgColor value="FFFFFF"> | ||
| 1167 | <param name=font value="Helvetica-plain-14"> | ||
| 1168 | <param name="rootTitle" value="$options->{doctitle};book.gif,o_book.gif;;$options->{doctitle}"> | ||
| 1169 | <param name="expanded" value="true"> | ||
| 1170 | <param name="baseURL" value="./"> | ||
| 1171 | |||
| 1172 | EOA | ||
| 1173 | |||
| 1174 | # add hints for all pages | ||
| 1175 | foreach my $chapter (1..$td->{pageNr}) | ||
| 1176 | { | ||
| 1177 | # get short path in the required format (levels delimited by slashes) | ||
| 1178 | my @apath=@{$me->page($chapter)->path(type=>'spath', mode=>'array')}; | ||
| 1179 | my $apath=join('/', @apath); | ||
| 1180 | die "[Fatal] Missing levels in $apath.\n" if grep(not (defined), @apath); | ||
| 1181 | |||
| 1182 | # update applet string | ||
| 1183 | $applet.=join('', qq(<param name="item$chapter" value="$apath;book.gif,o_book.gif;), $me->buildFilename($chapter), qq(,Data;$apath">\n)); | ||
| 1184 | } | ||
| 1185 | |||
| 1186 | # complete applet code | ||
| 1187 | $applet.="\n</applet>\n\n"; | ||
| 1188 | |||
| 1189 | # ok, replace the wildcard | ||
| 1190 | s/TREE_APPLET_TOC/$applet/g; | ||
| 1191 | } | ||
| 1192 | |||
| 1193 | # finally, add the transform lines to the result string | ||
| 1194 | push(@result, $_); | ||
| 1195 | } | ||
| 1196 | |||
| 1197 | # close template file | ||
| 1198 | close(TPL); | ||
| 1199 | |||
| 1200 | # supply result | ||
| 1201 | join('', @result); | ||
| 1202 | } | ||
| 1203 | |||
| 1204 | |||
| 1205 | # build a toc | ||
| 1206 | sub _toc | ||
| 1207 | { | ||
| 1208 | # get and check parameters | ||
| 1209 | my ($me)=@_; | ||
| 1210 | confess "[BUG] Missing object parameter.\n" unless $me; | ||
| 1211 | confess "[BUG] Object parameter is no ", __PACKAGE__, " object.\n" unless ref $me and $me->isa(__PACKAGE__); | ||
| 1212 | |||
| 1213 | # declare variables | ||
| 1214 | my (@result); | ||
| 1215 | |||
| 1216 | # common preprocessing | ||
| 1217 | my $td=$me->preprocessData(1); | ||
| 1218 | |||
| 1219 | # add entries for all pages | ||
| 1220 | foreach my $chapter (1..$td->{pageNr}) | ||
| 1221 | { | ||
| 1222 | # get short path in the required format (levels delimited by slashes) | ||
| 1223 | my @apath=@{$me->page($chapter)->path(type=>'spath', mode=>'array')}; | ||
| 1224 | my $apath=join('/', @apath); | ||
| 1225 | die "[Fatal] Missing levels in $apath.\n" if grep(not (defined), @apath); | ||
| 1226 | |||
| 1227 | # add string | ||
| 1228 | push(@result, join('', qq(<p class="s), scalar(@apath), qq("><a href="), $me->buildFilename($chapter), qq(">$apath[-1]</a></p>\n))); | ||
| 1229 | } | ||
| 1230 | |||
| 1231 | # supply result | ||
| 1232 | join('', @result); | ||
| 1233 | } | ||
| 1234 | |||
| 1235 | |||
| 1236 | |||
| 1237 | |||
| 1238 | # flag successful loading | ||
| 1239 | 1; | ||
| 1240 | |||
| 1241 | # = POD TRAILER SECTION ================================================================= | ||
| 1242 | |||
| 1243 | =pod | ||
| 1244 | |||
| 1245 | =head1 NOTES | ||
| 1246 | |||
| 1247 | |||
| 1248 | =head1 SEE ALSO | ||
| 1249 | |||
| 1250 | =over 4 | ||
| 1251 | |||
| 1252 | |||
| 1253 | |||
| 1254 | =back | ||
| 1255 | |||
| 1256 | |||
| 1257 | =head1 SUPPORT | ||
| 1258 | |||
| 1259 | A PerlPoint mailing list is set up to discuss usage, ideas, | ||
| 1260 | bugs, suggestions and translator development. To subscribe, | ||
| 1261 | please send an empty message to perlpoint-subscribe@perl.org. | ||
| 1262 | |||
| 1263 | If you prefer, you can contact me via perl@jochen-stenzel.de | ||
| 1264 | as well. | ||
| 1265 | |||
| 1266 | =head1 AUTHOR | ||
| 1267 | |||
| 1268 | Copyright (c) Jochen Stenzel (perl@jochen-stenzel.de), 2004-2006. | ||
| 1269 | All rights reserved. | ||
| 1270 | |||
| 1271 | This module is free software, you can redistribute it and/or modify it | ||
| 1272 | under the terms of the Artistic License distributed with Perl version | ||
| 1273 | 5.003 or (at your option) any later version. Please refer to the | ||
| 1274 | Artistic License that came with your Perl distribution for more | ||
| 1275 | details. | ||
| 1276 | |||
| 1277 | The Artistic License should have been included in your distribution of | ||
| 1278 | Perl. It resides in the file named "Artistic" at the top-level of the | ||
| 1279 | Perl source tree (where Perl was downloaded/unpacked - ask your | ||
| 1280 | system administrator if you dont know where this is). Alternatively, | ||
| 1281 | the current version of the Artistic License distributed with Perl can | ||
| 1282 | be viewed on-line on the World-Wide Web (WWW) from the following URL: | ||
| 1283 | http://www.perl.com/perl/misc/Artistic.html | ||
| 1284 | |||
| 1285 | |||
| 1286 | =head1 DISCLAIMER | ||
| 1287 | |||
| 1288 | This software is distributed in the hope that it will be useful, but | ||
| 1289 | is provided "AS IS" WITHOUT WARRANTY OF ANY KIND, either expressed or | ||
| 1290 | implied, INCLUDING, without limitation, the implied warranties of | ||
| 1291 | MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE. | ||
| 1292 | |||
| 1293 | The ENTIRE RISK as to the quality and performance of the software | ||
| 1294 | IS WITH YOU (the holder of the software). Should the software prove | ||
| 1295 | defective, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR | ||
| 1296 | CORRECTION. | ||
| 1297 | |||
| 1298 | IN NO EVENT WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MAY CREATE, | ||
| 1299 | MODIFY, OR DISTRIBUTE THE SOFTWARE BE LIABLE OR RESPONSIBLE TO YOU OR TO | ||
| 1300 | ANY OTHER ENTITY FOR ANY KIND OF DAMAGES (no matter how awful - not even | ||
| 1301 | if they arise from known or unknown flaws in the software). | ||
| 1302 | |||
| 1303 | Please refer to the Artistic License that came with your Perl | ||
| 1304 | distribution for more details. | ||
| 1305 |