<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="index.html">indoc</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Volumes and Instructions</b></li></ul></div>
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Model. </b>Conceptually, an Indoc project has either one or two volumes. The source for
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Project instructions. </b>The main instructions file for an Indoc project is, as noted earlier, at:
<pclass="commentary">The third, also optional, part of a <spanclass="extract"><spanclass="extract-syntax">volume</span></span> instruction specifies the
the title plus <spanclass="extract"><spanclass="extract-syntax">.txt</span></span>: for example, <spanclass="extract"><spanclass="extract-syntax">Writing with Inform.txt</span></span>. But we can
use <spanclass="extract"><spanclass="extract-syntax">= X</span></span> to specify that it should be <spanclass="extract"><spanclass="extract-syntax">X</span></span> instead.
some navigation icons such as <spanclass="extract"><spanclass="extract-syntax">arrow-up.png</span></span>. The instruction <spanclass="extract"><spanclass="extract-syntax">images: X</span></span>
adds the directory <spanclass="extract"><spanclass="extract-syntax">X</span></span> to this source list.
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Durham Core metadata. </b>If the project needs to generate Epub books, then these will need to have
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. Targets. </b>The instructions file typically begins as above, but then goes into a
<pclass="commentary">where <spanclass="extract"><spanclass="extract-syntax">IDENTIFIER</span></span> is its name. Targets, as noted in the introduction,
for example, has targets called <spanclass="extract"><spanclass="extract-syntax">plain</span></span>, <spanclass="extract"><spanclass="extract-syntax">website</span></span>, <spanclass="extract"><spanclass="extract-syntax">linux_app</span></span> and so on.
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. Symbols. </b>The instruction <spanclass="extract"><spanclass="extract-syntax">declare: SYMBOL</span></span> creates the symbol <spanclass="extract"><spanclass="extract-syntax">SYMBOL</span></span>. These exist
<pclass="commentary">The symbol <spanclass="extract"><spanclass="extract-syntax">indoc</span></span> is always declared, but by default no other symbols are.
Lastly, <spanclass="extract"><spanclass="extract-syntax">undeclare: SYMBOL</span></span> removes a symbol.
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. Other instructions. </b><spanclass="extract"><spanclass="extract-syntax">follow: I</span></span> tells Indoc to follow the instructions file <spanclass="extract"><spanclass="extract-syntax">I</span></span>. This works
rather like <spanclass="extract"><spanclass="extract-syntax">#include</span></span> in C, or similar languages. If the <spanclass="extract"><spanclass="extract-syntax">follow:</span></span> is
<pclass="commentary">says that markup notations like <spanclass="extract"><spanclass="extract-syntax">^{@Andrew Plotkin}</span></span> put a name into the index,
which should be an index entry of category <spanclass="extract"><spanclass="extract-syntax">name</span></span>, and should be inverted,
in that it will be alphabetised under "Plotkin, Andrew". The text <spanclass="extract"><spanclass="extract-syntax">headword</span></span>
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. Miscellaneous settings. </b>There are a great many of these, but most are set to sensible defaults,
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">alphabetization</span></span> sets the index sorting algorithm. The default is
<spanclass="extract"><spanclass="extract-syntax">letter-by-letter</span></span>; the alternative is <spanclass="extract"><spanclass="extract-syntax">word-by-word</span></span>. The difference is
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">assume_Public_Library</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">change_logs_directory</span></span> is the path to a directory holding Inform release
change log files. By default, this will be <spanclass="extract"><spanclass="extract-syntax">Documentation/Change Logs</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">contents_leafname</span></span> is the (unextended) leafname to give the HTML contents
page. The default is <spanclass="extract"><spanclass="extract-syntax">index</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">contents_expandable</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This sets
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">css_source_file</span></span> is the filename of the CSS style sheet to use. The default
is the <spanclass="extract"><spanclass="extract-syntax">base.css</span></span> file included in the Indoc distribution.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">definitions_filename</span></span> is the filename to use if you would like Indoc to
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">definitions_index_filename</span></span> is the leafname to use for the General Index
in the documentation. The default is <spanclass="extract"><spanclass="extract-syntax">general_index.html</span></span>. This
has nothing to do with the <spanclass="extract"><spanclass="extract-syntax">definitions_filename</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">destination</span></span> is the directory into which output is generated. The default
is <spanclass="extract"><spanclass="extract-syntax">Documentation/Output</span></span>. Note that specifying <spanclass="extract"><spanclass="extract-syntax">-to X</span></span> at the command line
overrides this setting: if <spanclass="extract"><spanclass="extract-syntax">-to</span></span> is used, <spanclass="extract"><spanclass="extract-syntax">destination</span></span> is ignored.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">examples_directory</span></span> is the directory holding the Example files. The default
is <spanclass="extract"><spanclass="extract-syntax">Documentation/Examples</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">examples_alphabetical_leafname</span></span> is the leafname to use for the alphabetical
index of examples in the documentation. The default is <spanclass="extract"><spanclass="extract-syntax">examples_alphabetical.html</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">examples_granularity</span></span> is 1, 2, or 3. It can never be less than <spanclass="extract"><spanclass="extract-syntax">granularity</span></span>,
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">examples_mode</span></span> is <spanclass="extract"><spanclass="extract-syntax">open</span></span> or <spanclass="extract"><spanclass="extract-syntax">openable</span></span>, and is by default <spanclass="extract"><spanclass="extract-syntax">open</span></span>. Open means
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">examples_numerical_leafname</span></span> is the leafname to use for the numerical
index of examples in the documentation. The default is <spanclass="extract"><spanclass="extract-syntax">examples_numerical.html</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">format</span></span> is the most important of all the settings, and is <spanclass="extract"><spanclass="extract-syntax">HTML</span></span> or <spanclass="extract"><spanclass="extract-syntax">text</span></span>,
but by default <spanclass="extract"><spanclass="extract-syntax">HTML</span></span> unless the target name is <spanclass="extract"><spanclass="extract-syntax">plain</span></span>, in which case <spanclass="extract"><spanclass="extract-syntax">text</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">granularity</span></span> is 1, 2, or 3. The default is 3 unless the target is called
<spanclass="extract"><spanclass="extract-syntax">webpage</span></span> or <spanclass="extract"><spanclass="extract-syntax">plain</span></span>, in which case it is 1. This specifies how much the
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">html_for_Inform_application</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">images_copy</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">yes</span></span>. In this mode,
any needed image files are copied into place into the <spanclass="extract"><spanclass="extract-syntax">images_path</span></span>. (The
alternative assumes they are already there, and should be used if <spanclass="extract"><spanclass="extract-syntax">images_path</span></span>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">images_path</span></span> is where the generated HTML expects to find its image files.
The default is <spanclass="extract"><spanclass="extract-syntax">~~/Images/</span></span>, where <spanclass="extract"><spanclass="extract-syntax">~~</span></span> means the destination directory:
that is, the default is a subdirectory called <spanclass="extract"><spanclass="extract-syntax">Images</span></span> of the destination.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">inform_definitions_mode</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">javascript</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">yes</span></span>. This indicates
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">link_to_extensions_index</span></span> is meaningful only if <spanclass="extract"><spanclass="extract-syntax">html_for_Inform_application</span></span>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">manifest_leafname</span></span> is meaningful only if <spanclass="extract"><spanclass="extract-syntax">html_for_Inform_application</span></span>
is set, and is by default <spanclass="extract"><spanclass="extract-syntax">manifest.txt</span></span>. This provides a cross-reference
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">navigation</span></span> is the design used for navigation links in the HTML produced.
There are currently six designs, called <spanclass="extract"><spanclass="extract-syntax">architect</span></span>, <spanclass="extract"><spanclass="extract-syntax">lacuna</span></span>, <spanclass="extract"><spanclass="extract-syntax">midnight</span></span>,
<spanclass="extract"><spanclass="extract-syntax">roadsign</span></span>, <spanclass="extract"><spanclass="extract-syntax">twilight</span></span>, and <spanclass="extract"><spanclass="extract-syntax">unsigned</span></span>; the default is <spanclass="extract"><spanclass="extract-syntax">roadsign</span></span>, though
inside the Inform applications, the design chosen is usually <spanclass="extract"><spanclass="extract-syntax">architect</span></span>.
If the format is <spanclass="extract"><spanclass="extract-syntax">text</span></span> not <spanclass="extract"><spanclass="extract-syntax">HTML</span></span>, then the design is always <spanclass="extract"><spanclass="extract-syntax">lacuna</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">retina_images</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This indicates
available: <spanclass="extract"><spanclass="extract-syntax">paste@2x.png</span></span> and <spanclass="extract"><spanclass="extract-syntax">create@2x.png</span></span> respectively.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">support_creation</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This indicates
so it should always be <spanclass="extract"><spanclass="extract-syntax">no</span></span> unless <spanclass="extract"><spanclass="extract-syntax">html_for_Inform_application</span></span> is <spanclass="extract"><spanclass="extract-syntax">yes</span></span>.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">suppress_fonts</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. If <spanclass="extract"><spanclass="extract-syntax">yes</span></span>, this
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">toc_granularity</span></span> is 1, 2, or 3. It can never be less than <spanclass="extract"><spanclass="extract-syntax">granularity</span></span>,
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">top_and_tail</span></span> specifies a prototype HTML file to follow for the more
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">top_and_tail_sections</span></span> is the same as <spanclass="extract"><spanclass="extract-syntax">top_and_tail</span></span>, but for individual
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">treat_code_as_verbatim</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">yes</span></span>. This
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">wrapper</span></span> can be <spanclass="extract"><spanclass="extract-syntax">EPUB</span></span>, <spanclass="extract"><spanclass="extract-syntax">zip</span></span> or <spanclass="extract"><spanclass="extract-syntax">none</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">none</span></span>. The wrapper
is put around the whole mass of generated HTML; <spanclass="extract"><spanclass="extract-syntax">EPUB</span></span> makes the result an
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">XHTML</span></span> can be <spanclass="extract"><spanclass="extract-syntax">yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>. This forces the HTML we
produce to conform to XHTML 1.1 Strict. If the <spanclass="extract"><spanclass="extract-syntax">wrapper</span></span> is <spanclass="extract"><spanclass="extract-syntax">EPUB</span></span>, then
this is automatically set to <spanclass="extract"><spanclass="extract-syntax">yes</span></span>.