Script file structure
Previous: LPML alpha ] [ Top: LPML alpha ] [ Next: Initial scan ]

This is the overall layout of the file, and indeed of most single-file Perl scripts. As such, it will serve as a useful pattern someday when this project gets to the point where patterns are explicitly supported.

I don't know how other people write Perl scripts, but I start out by processing the input, so I can quit early if there's already a problem. Then globals and subroutine declaration (in most of my larger pieces, of course, I eschew globals and I put subroutines into separate files.) Then the meat of the code, which executes the following basic algorithm:
  • Scan
    The initial scan reads the file and creates a list of items keyed by name. Each item's information includes its label (for printing into the documentation) and its initial text pieces (for tangling.) Note that some pieces concatenate onto other items than the one they're in; in this case, the label may not even be known before the first text piece is added, but that won't stop us, we're Perl.
  • Tangle
    Once the scan is complete, we have all the information we need to generate the text targets defined by this file. (That's tangling.) So we get that task out of the way. The other reason that tangle goes first is that in a later version than this, the tangle will accumulate index data which will be used during the weave phase (where documentation is generated.)
  • Prepare indices
    Using information gained during the initial scan and possibly augmented during tangle, we can prepare various indices which can then be used in the generation of the documentation. At the moment, these indices are simply a hierarchical list of items and a list of objects generated; no information is created during tangle. Knuth's original WEB, of course, generated a comprehensive list of crossreferences and a list of identifiers during tangle.
  • Weave
    The weave step generates the documentation, one page per item, by name. If an item is called "index" (thus generating "index.html") then it will be omitted from the list of items, and its label will be available for use in subsequent pages. The <insert> tag is replaced by the label of its item, suitably formatted. Text pieces are formatted as code blocks.
# This is the lpml alpha Perl script.
# Copyright (c) 2000 Vivtek.  All rights reserved except those explicitly granted
# under the GNU Public License.
# for more information.

See Process arguments and open source file

See Initial scan
See Tangle: write code output
See Prepare indices
See Weave: Write documentation pages

See Clean up afterwards
Previous: LPML alpha ] [ Top: lpml alpha ] [ Next: Initial scan ]

This code and documentation are released under the terms of the GNU license. They are copyright (c) 2000-2006, Vivtek. All rights reserved except those explicitly granted under the terms of the GNU license.

Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.