What Indoc is, and its limited but complicated uses.
§1. Intest is a command line tool for generating (mainly) HTML or EPUB format documentation. A million of those have been written, and Indoc has no ambition to replace them. It is needed because Inform 7's documentation source consists of many small text files with idiosyncratic markup, while its formatted HTML version needs to be indexed in elaborate ways.
Indoc is a purely command-line tool, used in building Inform but not in running it: it's not present in the Inform UI apps.
If you have compiled the standard distribution of the command-line tools
for Inform then the Indoc executable will be at indoc/Tangled/indoc/
.
Usage is very simple:
$ indoc/Tangled/indoc [OPTIONS] TARGET
By default, Indoc reads its source documentation from a direction called
Documentation
(with respect to the current working directory); the
option -from X
changes this path to X
, but in this manual we'll call
it Documentation
.
In addition to documentation files, which will be described later, Indoc also reads instruction files. At minimum it will read
Documentation/indoc-instructions.txt
but the option -instructions X
causes it to read X
as well. Instructions
files mainly specify indexing notations, or CSS styles, or miscellaneous
settings, but they group these under named "targets". For example:
windows_app { ... }
declares a target called windows_app
. (This is the form of HTML needed for
use inside the Windows UI application for Inform.) The idea here is that
there is probably no single form of HTML needed — it will be needed in
subtly different versions for different platforms: inside the app, as a
stand-alone website, inside an Epub ebook. These different forms are
called "targets". On any given run, Indoc generates a single target —
the one named on the command line.
The HTML produced is placed, by default, in the directory:
Documentation/Output
This can be changed with the option -to X
.
§2. When it runs, Indoc needs to know where it is installed in the file system. There is no completely foolproof, cross-platform way to know this (on some Unixes, a program cannot determine its own location), so Indoc decides by the following set of rules:
-at P
, for some path
P
, then we use that.
$INDOC_PATH
exists and is
non-empty, we use that.
indoc
, with
respect to the current working directory.
If you're not sure what Indoc has decided and suspect it may be wrong,
running Indoc with the -verbose
switch will cause it to print its belief
about its location as it starts up.
§3. Perhaps the ugliest thing Indoc does is to rewrite the Standard Rules extension, which comes supplied with Inform, so that its lines giving cross-references to documentation contain accurate references. These lines are special sentences such as:
Document kind_person at doc45 "3.17" "Men, women and animals".
Indoc looks for a contiguous block of lines in the form
Document ... at doc12.
and replaces it with a new block of lines containing up to date information.
This happens only if -rewrite-standard-rules X
is specified, with X
being
the filename of the Standard Rules.
§4. As a program, Indoc began as a rat's nest of Perl in 2002, and you can still see where the rats used to live. Like all too many quick-fix Perl scripts, it was still in use ten years later. In 2012, I spent some time tidying it up to generate better HTML, and made it a web (that is, a literate program). The original had produced typically sloppy turn-of-the-century HTML, with tables for layout and no CSS, and with many now-deprecated tags and elements. The 2012 edition, by contrast, needed to produce validatable XHTML 1.1 Strict in order to make Epubs which read roughly correctly in today's ebook-readers, and when they call this Strict they're not kidding. It took something like four weeks of spare evenings.
Just as I was finishing up, John Siracusa described a not dissimilar task on his then podcast (Hypercritical 85): "I was trying to think of a good analogy for what happens when you're a programmer and you have this sort of task in front of you. Is it, the cobbler's children have no shoes? ... You would expect someone who is a programmer to make some awesome system which would generate these three things. But when you're a programmer, you have the ability to do whatever you want really, really quickly in the crappiest possible way... And that's what I did. I wrote a series of incredibly disgusting Perl scripts."
This made me feel better. (Also that, as it turned out, we both asked Liza Daly for help when we got stuck trying to understand Epub: small world.) Nevertheless, in 2016, Indoc was rewritten in C, using the then-new Foundation library, and it received a further revision in 2019, when this documentation was finally written, 17 years after the program it documents.