<!--Weave of 'Introduction to Indoc' generated by 7-->
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../other.html">Other Tools</a></li><li><ahref="index.html">indoc</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Introduction to Indoc</b></li></ul><pclass="purpose">What Indoc is, and its limited but complicated uses.</p>
<pclass="inwebparagraph">By default, Indoc reads its source documentation from a direction called
<codeclass="display"><spanclass="extract">Documentation</span></code> (with respect to the current working directory); the
option <codeclass="display"><spanclass="extract">-from X</span></code> changes this path to <codeclass="display"><spanclass="extract">X</span></code>, but in this manual we'll call
it <codeclass="display"><spanclass="extract">Documentation</span></code>.
</p>
<pclass="inwebparagraph">In addition to documentation files, which will be described later, Indoc
also reads instruction files. At minimum it will read
<pclass="inwebparagraph">but the option <codeclass="display"><spanclass="extract">-instructions X</span></code> causes it to read <codeclass="display"><spanclass="extract">X</span></code> as well. Instructions
files mainly specify indexing notations, or CSS styles, or miscellaneous
settings, but they group these under named "targets". For example:
<pclass="inwebparagraph">declares a target called <codeclass="display"><spanclass="extract">windows_app</span></code>. (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.
</p>
<pclass="inwebparagraph">The HTML produced is placed, by default, in the directory:
</p>
<preclass="display">
<spanclass="plain">Documentation/Output</span>
</pre>
<pclass="inwebparagraph">This can be changed with the option <codeclass="display"><spanclass="extract">-to X</span></code>.
</p>
<pclass="inwebparagraph"><aid="SP2"></a><b>§2. </b>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:
</p>
<pclass="inwebparagraph"></p>
<ulclass="items"><li>(a) If the user, at the command line, specified <codeclass="display"><spanclass="extract">-at P</span></code>, for some path
<codeclass="display"><spanclass="extract">P</span></code>, then we use that.
</li><li>(b) Otherwise, if the host operating system can indeed tell us where the
executable is, we use that. This is currently implemented only on MacOS,
Windows and Linux.
</li><li>(c) Otherwise, if the environment variable <codeclass="display"><spanclass="extract">$INDOC_PATH</span></code> exists and is
non-empty, we use that.
</li><li>(d) And if all else fails, we assume that the location is <codeclass="display"><spanclass="extract">indoc</span></code>, with
respect to the current working directory.
</li></ul>
<pclass="inwebparagraph">If you're not sure what Indoc has decided and suspect it may be wrong,
running Indoc with the <codeclass="display"><spanclass="extract">-verbose</span></code> switch will cause it to print its belief
about its location as it starts up.
</p>
<pclass="inwebparagraph"><aid="SP3"></a><b>§3. </b>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:
</p>
<preclass="display">
<spanclass="plain">Document kind_person at doc45 "3.17" "Men, women and animals".</span>
</pre>
<pclass="inwebparagraph">Indoc looks for a contiguous block of lines in the form
</p>
<preclass="display">
<spanclass="plain">Document ... at doc12.</span>
</pre>
<pclass="inwebparagraph">and replaces it with a new block of lines containing up to date information.
</p>
<pclass="inwebparagraph">This happens only if <codeclass="display"><spanclass="extract">-rewrite-standard-rules X</span></code> is specified, with <codeclass="display"><spanclass="extract">X</span></code> being
the filename of the Standard Rules.
</p>
<pclass="inwebparagraph"><aid="SP4"></a><b>§4. </b>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.
</p>
<pclass="inwebparagraph">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."
</p>
<pclass="inwebparagraph">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.
<ulclass="toc"><li><i>(This section begins Manual.)</i></li><li><ahref="M-vai.html">Continue with 'Volumes and Instructions'</a></li></ul><hrclass="tocbar">