Preliminaries

• A Brief Guide to Foundation - Notes on getting started with the Foundation library.

Chapter 1: Setting Up

Absolute basics.

• Foundation Module - Starting up and shutting down.

• POSIX Platforms - A version of our operating system interface suitable for POSIX-compliant operating systems.

• Windows Platform - A version of our operating system interface suitable for Microsoft Windows.

Chapter 2: Memory, Streams and Collections

Creating objects in memory, and forming lists, hashes, and text streams.

• Debugging Log - To write to the debugging log, a plain text file which traces what we're doing, in order to assist those lost souls debugging it.

• Memory - To allocate memory suitable for the dynamic creation of objects of different sizes, placing some larger objects automatically into doubly linked lists and assigning each a unique allocation ID number.

• Foundation Classes - To declare the object classes used in the Foundation module.

• Locales - Locales are what operating-system people call the text encodings used when interacting with them: in filenames, or when printing to the console.

• Streams - Support for writing structured textual output, perhaps to the screen, to a file, or to a flexible-sized wide string.

• Writers and Loggers - Formatted text output to streams.

• Methods - General support for something approximating method calls.

• Linked Lists and Stacks - A simple implementation for single-linked lists of objects allocated by Foundation's memory manager, and for last-in-first-out stacks of same.

• Dictionaries - A simple implementation for a flexible-sized dictionary of key-value pairs.

• Trees - To provide heterogeneous tree structures, where a node can be any structure known to the Foundation memory manager.

Chapter 3: The Operating System

Dealing with the host operating system.

• Error Messages - A basic system for command-line tool error messages.

• Command Line Arguments - To parse the command line arguments with which inweb was called, and to handle any errors it needs to issue.

• Pathnames - Locations of hypothetical or real directories in the filing system.

• Filenames - Names of hypothetical or real files in the filing system.

• Case-Insensitive Filenames - On some of the Unix-derived file systems on which Inform runs, filenames are case-sensitive, so that FISH and fish might be different files. This makes extension files, installed by the user, prone to being missed. The code in this section provides a routine to carry out file opening as if filenames are case-insensitive, and is used only for extensions.

• Shell - Sending commands to the shell, on Unix-like platforms, or simulating this on Windows.

• Directories - Scanning directories on the host filing system.

• Time - Managing how we record and use the current time and date.

Chapter 4: Text Handling

Reading, writing and parsing text.

• Characters - Individual characters.

• C Strings - A minimal library for handling C-style strings.

• Wide Strings - A minimal library for handling wide C strings.

• String Manipulation - Convenient routines for manipulating strings of text.

• Tab Stops - Reading strings where tab characters need to be interpreted as if spaces had been used for the same visual effect.

• Text Files - To read text files of whatever flavour, one line at a time.

• Preprocessor - A simple, general-purpose preprocessor for text files, expanding macros and performing repetitions.

• Tries and Avinues - To examine heads and tails of text, to see how it may inflect.

• Finite State Machines - To provide simple scanning parsers based on finite state machines.

• Pattern Matching - To provide a limited regular-expression parser.

• JSON - To read, validate and write JSON data interchange material.

Chapter 5: Generating Websites

For making individual web pages, or gathering them into mini-sites or ebooks.

• HTML - Utility functions for writing HTML.

• HTML Entities - Utility functions for dealing with those ampersanded paraphrases of characters which seemed like a good idea in around the year 2000.

• Markdown - To store the results of parsing the Markdown markup notation.

• Markdown Phase I - Phase I of the Markdown parser: reading a series of lines into a tree of container and leaf blocks.

• Markdown Phase II - Phase II of the Markdown parser: fragmenting inline material into emphasis, links, backticked code and so forth.

• Markdown Rendering - To render a Markdown tree as HTML.

• Markdown Variations - To specify modified versions of the Markdown markup syntax.

• Inform-Flavoured Markdown - A form of Markdown adapted to the needs of the Inform tools.

• Epub Ebooks - To provide for wrapping up sets of HTML files into ePub ebooks.

Chapter 6: Media

Examining image and sound files.

• Binary Files - Routines for reading raw data from binary files.

• Image Dimensions - These utility routines look at the headers of JPEG and PNG files to find the pixel dimensions of any images supplied by the user for cover art and figures.

• Sound Durations - These utility routines look at the headers of AIFF, OGG Vorbis or MIDI files to find the durations, and verify that they are what they purport to be.

Chapter 7: Semantic Versioning

For reading, storing and comparing standard semantic version numbers.

• Version Numbers - Semantic version numbers such as 3.7.1.

• Version Number Ranges - Ranges of acceptable version numbers.

• Licence Data - Storing names and standard SPDX identifiers for common open source licences.

• SPDX Licenses - This section was mechanically generated from the JSON file provided by https://spdx.org/licenses/. The version used was 747753e, dated 2024-04-24.

Chapter 8: Literate Programming

Configuring LP syntax, parsing raw LP material, and tangling it.

• Web Structure - To read the structure of a literate programming web from a path in the file system.

• Bibliographic Data for Webs - To manage key-value pairs of bibliographic data, metadata if you like, associated with a given web.

• Web Contents Pages - To read the structure of a literate programming web from a path in the file system.

• Single-File Webs - To scan a single-file web looking for indications of its syntax and/or programming language, and to assemble a minimal web structure around its one unit of source.

• Web Modules - To search for included modules, and track dependencies between them.

• Web Ranges - Short textual descriptions of a range of sections or chapters in a web.

• Literate Source - To parse and represent units of literate source text.

• Line Classification - Literate source is usually very line-based, and so parsing it is a matter of deciding what sort of thing each line represents.

• Web Errors - To store and sometimes to issue errors arising from parsing malformed webs of literate source text.

• Web Syntax - To manage possible syntaxes for webs.

• Holons - To manage fragments of eventually-compiled code, or "holons", within each section.

• Holon Syntax - Constructing a finite state machine for the parsing of code in holons.

• Tangle Targets - Most webs tangle to just one program, but we do support multiple targets, which can be in different programming languages.

• The Tangler - Transforming code written in literate programming notation into regular code, fit for a compiler.

• Build Files - Manages the build metadata for an inweb project.

Chapter 9: Programming

Reading some basic syntax of different programming languages.

• Programming Languages - Defining the programming languages supported by our LP system, loading in their definitions from files.

• Code Analysis - Here we analyse the code in the web, enabling us to see how functions and data structures are used within the program.

• Conditional Compilation - Thematic tags can be used to mark code as being included in a tangle but only within markers for conditional compilation.

• Enumerated Constants - To define sequentially numbered values for families of constants.

• Types and Functions - Basic support for languages to recognise structure and function declarations.

• Ctags Support - Constructing a suitable ctags file for a web.

• Reserved Words - Managing reserved words, that is, significant identifiers, for programming languages.

• The Painter - A simple syntax-colouring engine.

• Language Methods - To characterise the relevant differences in behaviour between the various programming languages supported.

• ACME Support - For generic programming languages by the ACME corporation.

• C-Like Languages - To provide special features for the whole C family of languages.

• InC Support - To support a modest extension of C called InC.

Chapter 10: Weaving

Weaving to a variety of different human-readable formats.

• Weaving Details - Annotations to a LP tree to accommodate weaving.

• The Swarm - To feed multiple output requests to the weaver, and to present weaver results, and update indexes or contents pages.

• Patterns - Managing weave patterns, which are bundled configuration settings for weaving.

• Assets, Plugins and Colour Schemes - Mainly for HTML, to add the necessary JavaScript for unusual requirements such as equations or footnotes.

• The Collater - To collate material generated by the weaver into finished, fully-woven files.

• The Weaver - To weave a portion of the code into a tree of rendering instructions.

• The Weaver of Text - To write rendering instructions for commentary or source code text.

• Weave Tree - The weaver produces a tree of rendering instructions as its main intermediate representation, and this section defines that tree.

• Format Methods - To characterise the relevant differences in behaviour between the various weaving formats offered, such as HTML, ePub, or TeX.

• Plain Text Format - To provide for weaving in plain text format, which is not very interesting, but ought to be available.

• TeX Format - To provide for weaving in the standard maths and science typesetting software, TeX.

• HTML Formats - To provide for weaving into HTML and into EPUB books.

• Debugging Format - A format which renders as a plain-text serialisation of the weave tree, useful only for testing the weaver.

• TeX Utilities - A few conveniences for using weaving with TeX.

Chapter 11: Project Management

Additional features for managing projects which may have multiple webs.

• Makefiles - Constructing a suitable makefile for a simple inweb project.

• Git Support - Constructing a suitable gitignore file for a simple inweb project.

• Readme Writeme - To construct Readme and similar files.

• Colonies - Cross-referencing multiple webs gathered together.