mirror of
https://github.com/ganelson/inform.git
synced 2024-06-01 07:48:35 +03:00
196 lines
11 KiB
HTML
196 lines
11 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>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<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="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/ConsoleText-Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/docs/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/docs/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'Introduction to Indoc' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</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></div>
|
|
<p class="purpose">What Indoc is, and its limited but complicated uses.</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></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="commentary">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="commentary">If you have compiled the standard distribution of the command-line tools
|
|
for Inform then the Indoc executable will be at <span class="extract"><span class="extract-syntax">indoc/Tangled/indoc/</span></span>.
|
|
Usage is very simple:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">indoc/Tangled/indoc</span><span class="ConsoleText-plain-syntax"> [OPTIONS] TARGET</span>
|
|
</pre>
|
|
<p class="commentary">By default, Indoc reads its source documentation from a direction called
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">Documentation</span></span> (with respect to the current working directory); the
|
|
option <span class="extract"><span class="ConsoleText-extract-syntax">-from X</span></span> changes this path to <span class="extract"><span class="ConsoleText-extract-syntax">X</span></span>, but in this manual we'll call
|
|
it <span class="extract"><span class="ConsoleText-extract-syntax">Documentation</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">In addition to documentation files, which will be described later, Indoc
|
|
also reads instruction files. At minimum it will read
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Documentation/indoc-instructions.txt</span>
|
|
</pre>
|
|
<p class="commentary">but the option <span class="extract"><span class="extract-syntax">-instructions X</span></span> causes it to read <span class="extract"><span class="extract-syntax">X</span></span> 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="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> windows_app {</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<p class="commentary">declares a target called <span class="extract"><span class="extract-syntax">windows_app</span></span>. (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="commentary">The HTML produced is placed, by default, in the directory:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Documentation/Output</span>
|
|
</pre>
|
|
<p class="commentary">This can be changed with the option <span class="extract"><span class="extract-syntax">-to X</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></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>
|
|
|
|
<ul class="items"><li>(a) If the user, at the command line, specified <span class="extract"><span class="extract-syntax">-at P</span></span>, for some path
|
|
<span class="extract"><span class="extract-syntax">P</span></span>, 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 <span class="extract"><span class="extract-syntax">$INDOC_PATH</span></span> exists and is
|
|
non-empty, we use that.
|
|
</li><li>(d) And if all else fails, we assume that the location is <span class="extract"><span class="extract-syntax">indoc</span></span>, with
|
|
respect to the current working directory.
|
|
</li></ul>
|
|
<p class="commentary">If you're not sure what Indoc has decided and suspect it may be wrong,
|
|
running Indoc with the <span class="extract"><span class="extract-syntax">-verbose</span></span> switch will cause it to print its belief
|
|
about its location as it starts up.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></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="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Document kind_person at doc45 "3.17" "Men, women and animals".</span>
|
|
</pre>
|
|
<p class="commentary">Indoc looks for a contiguous block of lines in the form
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Document ... at doc12.</span>
|
|
</pre>
|
|
<p class="commentary">and replaces it with a new block of lines containing up to date information.
|
|
</p>
|
|
|
|
<p class="commentary">This happens only if <span class="extract"><span class="extract-syntax">-rewrite-standard-rules X</span></span> is specified, with <span class="extract"><span class="extract-syntax">X</span></span> being
|
|
the filename of the Standard Rules.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></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="commentary">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="commentary">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>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprevoff">❮</li><li class="progresscurrentchapter">M</li><li class="progresscurrent">iti</li><li class="progresssection"><a href="M-vai.html">vai</a></li><li class="progresssection"><a href="M-dm.html">dm</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-bsc.html">1</a></li><li class="progresschapter"><a href="2-ss.html">2</a></li><li class="progresschapter"><a href="3-iu.html">3</a></li><li class="progresschapter"><a href="4-nd.html">4</a></li><li class="progressnext"><a href="M-vai.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|