An overview of how Inweb works, with links to all of its important functions.


§1. Prerequisites.This page is to help readers to get their bearings in the source code for Inweb, which is a literate program or "web". Before diving in:

§2. Working out what to do, and what to do it to.Inweb is a C program, so it begins at main, in Program Control. PC works out where Inweb is installed, then calls Configuration, which reads the command line options.

The user's choices are stored in an inweb_instructions object, and Inweb is put into one of four modes: TANGLE_MODE, WEAVE_MODE, ANALYSE_MODE, or TRANSLATE_MODE.1 Inweb never changes mode: once set, it remains for the rest of the run. Inweb also acts on only one main web in any run, unless in TRANSLATE_MODE, in which case none.

Once it has worked through the command line, Configuration reads in the colony file, if one was given (see Making Weaves into Websites), and uses this to preset some settings: see Configuration::member_and_colony.

All errors in configuration are sent to Errors::fatal, from whose bourne no traveller returns.

§3. Program Control then resumes, calling Main::follow_instructions to act on the inweb_instructions object. If the user did specify a web to work on, PC then goes through three stages to understand it.

First, PC calls Main::load_web to read the web fully into memory — not only metadata such as its title, author, and section breakdown, but also the completely parsed text of the source. (It's possible to read webs only partially as metadata alone for speed, but we don't do that.) All this work is delegated to the foundation library, so if you're interested in how it's done, and in how webs are stored in memory, see there. The result, put briefly, is a single ls_web object, containing a list of ls_chapter objects for each chapter, each of which in turn is a list of ls_section objects for each section. There is always at least one ls_chapter, each of which has at least one ls_section.2 The "range text" for each chapter and section is set along the way, which affects leafnames used in woven websites.3

Where a web imports a module, as for instance the eastertide example does, WebStructure::get creates a ls_module object for each import. In any event, it also creates a module called "(main)" to represent the main, non-imported, part of the overall program. Each module object also refers to the ls_chapter and ls_section objects.4

§4. Taking action.Let's get back to Program Control, which has now set everything up and is about to take action. What it does depends on which of the four modes Inweb is in: WEAVE_MODE, TANGLE_MODE, ANALYSE_MODE or TRANSLATE_MODE. The latter amounts to very little, and is simply a catchall name for generating convenient addenda to webs of source code: makefiles, gitignore files and such.

And that is essentially it. Inweb winds up by returning exit code 1 if there were errors, or 0 if not, like a good Unix citizen.

§5. Adding to Inweb.Here's some miscellaneous advice for those who would like to add to Inweb:

1. To add a new command-line switch, declare at Configuration::read and add a field to inweb_instructions which holds the setting; don't act on it then and there, only in Program Control later. But we don't want these settings to proliferate: ask first if adding a feature to, say, Colonies (in foundation) or weave_pattern files would meet the same need.

2. To add new programming languages, try if possible to do everything you need with a new definition file alone: see Supporting Programming Languages. Failing that, foundation will need to be added to. see if making definition files more powerful would do it (for example, by making the ACME support more general-purpose). Failing even that, follow the model of C-Like Languages (in foundation): that is, add logic to Languages::read_definition which adds receiver functions to a language with a given name, or, preferably, some given declaration in the language definition file. On no account insert any language bias into The Weaver (in foundation) or The Tangler (in foundation).

3. To add new forms of weave output, try if possible to make a new pattern: see Advanced Weaving with Patterns. But this won't always be good enough. For example, "an HTML website but done differently" should be a pattern based on HTML.