mirror of
https://github.com/ganelson/inform.git
synced 2024-07-08 10:04:21 +03:00
183 lines
8.9 KiB
HTML
183 lines
8.9 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Introduction to Indoc</title>
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
<link href="../inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body>
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-src/Figures/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../compiler.html">compiler tools</a></li>
|
|
<li><a href="../other.html">other tools</a></li>
|
|
<li><a href="../extensions.html">extensions and kits</a></li>
|
|
<li><a href="../units.html">unit test tools</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorb/index.html">inblorb</a></li>
|
|
<li><a href="index.html"><span class="selectedlink">indoc</span></a></li>
|
|
<li><a href="../inpolicy/index.html">inpolicy</a></li>
|
|
<li><a href="../inrtps/index.html">inrtps</a></li>
|
|
</ul><h2>Foundation</h2><ul>
|
|
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'Introduction to Indoc' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../other.html">Other Tools</a></li><li><a href="index.html">indoc</a></li><li><a href="index.html#M">Manual</a></li><li><b>Introduction to Indoc</b></li></ul><p class="purpose">What Indoc is, and its limited but complicated uses.</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. </b>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.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">If you have compiled the standard distribution of the command-line tools
|
|
for Inform then the Indoc executable will be at <code class="display"><span class="extract">indoc/Tangled/indoc/</span></code>.
|
|
Usage is very simple:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">indoc/Tangled/indoc</span><span class="plain"> [OPTIONS] TARGET</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">By default, Indoc reads its source documentation from a direction called
|
|
<code class="display"><span class="extract">Documentation</span></code> (with respect to the current working directory); the
|
|
option <code class="display"><span class="extract">-from X</span></code> changes this path to <code class="display"><span class="extract">X</span></code>, but in this manual we'll call
|
|
it <code class="display"><span class="extract">Documentation</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">In addition to documentation files, which will be described later, Indoc
|
|
also reads instruction files. At minimum it will read
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Documentation/indoc-instructions.txt</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">but the option <code class="display"><span class="extract">-instructions X</span></code> causes it to read <code class="display"><span class="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:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">windows_app {</span>
|
|
<span class="plain">...</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">declares a target called <code class="display"><span class="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>
|
|
|
|
<p class="inwebparagraph">The HTML produced is placed, by default, in the directory:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Documentation/Output</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This can be changed with the option <code class="display"><span class="extract">-to X</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) If the user, at the command line, specified <code class="display"><span class="extract">-at P</span></code>, for some path
|
|
<code class="display"><span class="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 <code class="display"><span class="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 <code class="display"><span class="extract">indoc</span></code>, with
|
|
respect to the current working directory.
|
|
</li></ul>
|
|
<p class="inwebparagraph">If you're not sure what Indoc has decided and suspect it may be wrong,
|
|
running Indoc with the <code class="display"><span class="extract">-verbose</span></code> switch will cause it to print its belief
|
|
about its location as it starts up.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="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>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Document kind_person at doc45 "3.17" "Men, women and animals".</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Indoc looks for a contiguous block of lines in the form
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Document ... at doc12.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">and replaces it with a new block of lines containing up to date information.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">This happens only if <code class="display"><span class="extract">-rewrite-standard-rules X</span></code> is specified, with <code class="display"><span class="extract">X</span></code> being
|
|
the filename of the Standard Rules.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="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>
|
|
|
|
<p class="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>
|
|
|
|
<p class="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.
|
|
</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><i>(This section begins Manual.)</i></li><li><a href="M-vai.html">Continue with 'Volumes and Instructions'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|