Script file structure

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.)
• Weave
  The weave step generates the bulk of the documentation, one page per item, by name. The <insert> tag is replaced by the label of its item, suitably formatted. Text pieces are formatted as code blocks.
• Write index
  Finally, we write the index page or pages. This version of the process only defines a single index page; we'll probably want more control later.

#!/usr/local/bin/perl
# This is the XMLP alpha Perl script.
# Copyright (c) 2000 Vivtek.  All rights reserved except those explicitly granted
# under the GNU Public License.
# http://www.vivtek.com/xmlp/xmlp_alpha/index.html for more information.

See Process arguments and open source file


See Initial scan
See Tangle: write code output
See Write index page
See Weave: Write documentation pages

See Clean up afterwards