Script file structure
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 originalWEB, 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.
#!/usr/local/bin/perl # This is the lpml alpha Perl script. # Copyright (c) 2000 Vivtek. All rights reserved except those explicitly granted # under the GNU Public License. # http://www.vivtek.com/lpml/lpml_alpha/index.html 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 |
| 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. |
