An overview of the html module's role and abilities.
§1. Prerequisites. The html module is a part of the Inform compiler toolset. It is presented as a literate program or "web". Before diving in:
- (a) It helps to have some experience of reading webs: see inweb for more.
- (b) The module is written in C, in fact ANSI C99, but this is disguised by the fact that it uses some extension syntaxes provided by the inweb literate programming tool, making it a dialect of C called InC. See inweb for full details, but essentially: it's C without predeclarations or header files, and where functions have names like Tags::add_by_name rather than add_by_name.
- (c) This module uses other modules drawn from the compiler (see structure), and also uses a module of utility functions called foundation. For more, see A Brief Guide to Foundation (in foundation).
§2. Purpose. Many functions of the Inform toolset involve the generation of HTML in some way, but almost all of that work is actually done by the foundation module. If you're interested in how HTML pages are made, how tags are opened and closed, and such, see HTML (in foundation) and Epub Ebooks (in foundation). All of that code is general-purpose.
By contrast, the html module is very much a part of the Inform compiler and provides highly Inform-specific functions needed to make the intranet-like miniature websites it generates on the fly — problem pages, the Index, the extensions documentation. In particular, it offers:
- (a) clickable links to positions in source text, opening the Source panel in the Inform GUI apps as needed — see SourceLinks::link;
- (b) paste buttons which, when clicked, insert text into the Source panel, or which open certain files or folders — see Paste Buttons;
§3. Custom HTML link protocols. This seems a useful place to document something which the Inform GUI apps must provide. These render index, problem and extension mini-website pages in embedded web browser views: for example, Inform on MacOS is essentially running a copy of Safari (or rather, its underlying engine WebKit) under the hood to display these. The material displayed consists of standard web pages, except that there are two custom "transport protocols" or "URL schemas".
Protocols like this go under a number of names, partly because there are many subtly different ideas here which only experts can distinguish (see https://en.wikipedia.org/wiki/Application_layer for the entrance to the rabbit-hole). To us, anyway, protocols are the prefixes of URLs which end with a colon — all browsers recognise a standard set of these, of which http: https: and file: are by far the most commonly used.
Inform uses two non-standard ones in these internal pages, and so the GUI app must implement them for its embedded web engine:
- (a) source: is used in link hrefs to make source text references — see Source Links;
- (b) inform: is used both for links to internal or external pages generated by Inform, and also for image srcs. It behaves just like http:, except that it derives the location of a file from the given URL in a different way.
§4. The reason inform: is needed is that HTML files generated by Inform have no way to know the relative URLs necessary to access e.g. icon images for the World index, which will be in different places in the file system on different Inform apps. More formally, the specification of inform: is that —
- (a) inform://... is interpreted as a reference to one of the built-in images, i.e., to wherever the app has internally stashed the Inform distribution's directory resources/Imagery. Barring errors in Inform, or in the app, this should never 404.
- (b) For any path *, inform://Extensions/* should be fetched as * in the external resources area — that is, the place to which the app is installing new extensions. If no file was found, the link should simply do nothing: the application is required not to produce a 404 error page, or to blank out the page currently showing.
§5. Localisation. This module also contains a very simple system for "localisation" of text, that is, enabling the user to output text in multiple human languages. (Inform makes heavy use of this in the Index.) This may not appear at first to have anything to do with HTML, but in fact we will mainly use it when generating web pages in the Index, so it has some conveniences for stylistic markup as well.
See Localisation for details.