mirror of
https://github.com/ganelson/inform.git
synced 2024-07-03 07:24:58 +03:00
573 lines
29 KiB
HTML
573 lines
29 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Documentation Markup</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">
|
|
|
|
</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="../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 'Documentation Markup' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<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>Documentation Markup</b></li></ul></div>
|
|
<p class="purpose">How to mark up the plain-text source for Inform documentation.</p>
|
|
|
|
<ul class="toc"><li><a href="M-dm.html#SP1">§1. Volume files</a></li><li><a href="M-dm.html#SP6">§6. Inform-specific markup</a></li><li><a href="M-dm.html#SP9">§9. Indexing</a></li><li><a href="M-dm.html#SP17">§17. Example files</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. Volume files. </b>Documentation source is written in UTF-8 encoded plain text files. Except
|
|
for the markup notations described below, these really are plain text,
|
|
using skipped lines as paragraph breaks, and tabs for indented quotations:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> This is a paragraph of some text, which</span>
|
|
<span class="plain-syntax"> extends over perhaps many lines. All of the</span>
|
|
<span class="plain-syntax"> standard letters are allowed:</span>
|
|
|
|
<span class="plain-syntax"> The quick brown fox jumped over the lazy dog.</span>
|
|
<span class="plain-syntax"> Jinxed wizards pluck ivy from my quilt.</span>
|
|
<span class="plain-syntax"> Jackdaws love my big sphinx of quartz.</span>
|
|
|
|
<span class="plain-syntax"> The second para begins here, after the</span>
|
|
<span class="plain-syntax"> skipped line.</span>
|
|
</pre>
|
|
<p class="commentary">Note that line breaks in quotations are respected, whereas in regular
|
|
paragraphs they are not, and are treated as ordinary white space.
|
|
Lines in quotations can be indented still further with more tabs, and
|
|
those margins are preserved.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> For example:</span>
|
|
|
|
<span class="plain-syntax"> Instead of waiting when the prevailing wind is northwest:</span>
|
|
<span class="plain-syntax"> say "A fresh gust of wind bowls you over.";</span>
|
|
<span class="plain-syntax"> now the prevailing wind is east.</span>
|
|
</pre>
|
|
<p class="commentary">"Quotations", as this suggests, are often in fact code examples for some
|
|
programming language.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>In general, plain text means just what it says. Raw HTML should not be
|
|
included in documentation; but the syntax <b>Bold</n> and <i>Italic</i> is
|
|
an exception.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>Tables are formatted automatically whenever Indoc sees a pattern like this:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {*}Table 2 - Selected Elements</span>
|
|
<span class="plain-syntax"> Element Symbol Atomic number</span>
|
|
<span class="plain-syntax"> "Hydrogen" "H" 1</span>
|
|
<span class="plain-syntax"> "Iron" "Fe" 26</span>
|
|
<span class="plain-syntax"> "Zinc" "Zn" 30</span>
|
|
<span class="plain-syntax"> "Uranium" "U" 92</span>
|
|
</pre>
|
|
<p class="commentary">The top line is the title for the table, and then tab-delimited columns follow.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>Recall that volumes are divided into chapters, which are themselves divided
|
|
into sections. A line in the form:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> [Chapter: CHAPTERTITLE] SECTIONTITLE</span>
|
|
</pre>
|
|
<p class="commentary">begins a new chapter, and simultaneously begins its first section; the first
|
|
line of a volume file must be of this form. For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> [Chapter: Things] Descriptions</span>
|
|
</pre>
|
|
<p class="commentary">When it's time for a new section within the same chapter, the simpler form:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> [x] SECTIONTITLE</span>
|
|
</pre>
|
|
<p class="commentary">is used. Note that although chapters and sections are both numbered, this
|
|
numbering is automatically applied by Indoc, and does not appear in the source.
|
|
</p>
|
|
|
|
<p class="commentary">The final paragraph of a section is allowed to take a special form:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (See REFERENCE for PURPOSE.)</span>
|
|
</pre>
|
|
<p class="commentary">For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (See Text with substitutions for more on varying what is printed.)</span>
|
|
</pre>
|
|
<p class="commentary">Here, the <span class="extract"><span class="extract-syntax">REFERENCE</span></span> "Text with substitutions" is to another section in
|
|
the volume, having that title. Indoc will make this into a suitable link
|
|
in the generated HTML.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>When a paragraph begins with <span class="extract"><span class="extract-syntax">{CONTEXT:}</span></span>, it is included in the
|
|
generated documentation only for targets which match this context. A
|
|
context can be just a symbol created by <span class="extract"><span class="extract-syntax">declare:</span></span> in the instructions
|
|
file, so for example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {Linux:}The top secret DRM decoder ring is not included under Debian...</span>
|
|
</pre>
|
|
<p class="commentary">would be included only if the instruction <span class="extract"><span class="extract-syntax">declare: Linux</span></span> had been made
|
|
for the current target.
|
|
</p>
|
|
|
|
<p class="commentary">Contexts can however be compound, using the unary operator <span class="extract"><span class="extract-syntax">^</span></span> (negation),
|
|
the binary <span class="extract"><span class="extract-syntax">+</span></span> (conjunction), and binary <span class="extract"><span class="extract-syntax">,</span></span> (disjunction), which associate
|
|
in that order. The simplest case is
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {^Linux:}The top secret DRM decoder ring is in the Goodies folder...</span>
|
|
</pre>
|
|
<p class="commentary">which is included if and only if <span class="extract"><span class="extract-syntax">Linux</span></span> has not been declared. More elaborate
|
|
examples would be:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {^alpha,beta+gamma:}</span>
|
|
</pre>
|
|
<p class="commentary">which is true if either <span class="extract"><span class="extract-syntax">alpha</span></span> is undeclared, or if both <span class="extract"><span class="extract-syntax">beta</span></span> and <span class="extract"><span class="extract-syntax">gamma</span></span>
|
|
are declared; and
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {^(alpha,beta)+gamma:}</span>
|
|
<span class="plain-syntax"> {^alpha+^beta+gamma:}</span>
|
|
</pre>
|
|
<p class="commentary">which are both true if <span class="extract"><span class="extract-syntax">alpha</span></span> and <span class="extract"><span class="extract-syntax">beta</span></span> are undeclared but <span class="extract"><span class="extract-syntax">gamma</span></span> is
|
|
declared.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. Inform-specific markup. </b>A quotation beginning with <span class="extract"><span class="extract-syntax">{*}</span></span> is given a "paste" button allowing its
|
|
content to be pasted into the Source pane of an Inform project — though
|
|
of course, only for forms of the documentation appearing inside the Inform
|
|
UI app: it would be meaningless elsewhere.
|
|
</p>
|
|
|
|
<p class="commentary">A quotation beginning with <span class="extract"><span class="extract-syntax">{**}</span></span> is a continuation of the previous
|
|
paste-this-in quotation.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>In Inform documentation, the formal specification of a phrase can be
|
|
marked as in this example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> {defn ph_randomdesc}a/-- random (description of values) ... value</span>
|
|
<span class="plain-syntax"> This phrase makes a uniformly random choice...</span>
|
|
<span class="plain-syntax"> ...the result is the special value "nothing".</span>
|
|
<span class="plain-syntax"> {end}</span>
|
|
</pre>
|
|
<p class="commentary">The markers <span class="extract"><span class="extract-syntax">{defn ph_randomdesc}</span></span> and <span class="extract"><span class="extract-syntax">{end}</span></span>, which bookend the definition,
|
|
are invisible in the HTML output, but are used in the cross-referencing
|
|
material which Indoc produces for the benefit of Inform.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>The Index pane, and problem messages, need to link into the documentation
|
|
inside the Inform app. We can prepare for this by tagging the opening line
|
|
of a section like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> [x] Rooms and the map {kind_room} {MAP} {PM_SameKindEquated}</span>
|
|
</pre>
|
|
<p class="commentary">This applies three tags to the section: <span class="extract"><span class="extract-syntax">kind_room</span></span>, <span class="extract"><span class="extract-syntax">MAP</span></span> and <span class="extract"><span class="extract-syntax">PM_SameKindEquated</span></span>.
|
|
These are used by Inform for the helpful links in the Index or in problem
|
|
messages: for example, if the user generates the problem <span class="extract"><span class="extract-syntax">PM_SameKindEquated</span></span>
|
|
(this is its internal designation, of course), a link will appear, and it
|
|
will be to this section, "Rooms and the map".
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. Indexing. </b>Indoc volumes are indexed in the same sort of way that books are, and
|
|
the author has to mark up indexing terms as they arise. The notation
|
|
for this is an elaboration of a scheme devised by Knuth for the TeX Book.
|
|
At its simplest,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> I am the ^{walrus}.</span>
|
|
</pre>
|
|
<p class="commentary">becomes simply
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> I am the walrus.</span>
|
|
</pre>
|
|
<p class="commentary">in the generated HTML, but the position of the last word is added to a
|
|
new head-word in the index, "walrus". Where a double <span class="extract"><span class="extract-syntax">^</span></span> is used, the
|
|
index entry is invisible in the text itself, and only the position is
|
|
marked. Thus
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> I am the ^{walrus}.^^{Beatles}</span>
|
|
</pre>
|
|
<p class="commentary">A much more detailed description now follows.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b>Some generalities first. The index consists of "headwords", the terms being
|
|
indexed (which may or may not be just one word). Each headword is followed by
|
|
a comma-separated list of links to sections of the books - both books are
|
|
indexed, not just one. Links to the primary volume have the form "5.4"; links
|
|
to the secondary are the same, but italicised. The list of links is always
|
|
ordered numerically within the primary volume.
|
|
</p>
|
|
|
|
<p class="commentary">Headwords are alphabetized in a way which excludes initial "a", "an" or "the";
|
|
if the first word is a number from 1 to 12, it's replaced by the spelled
|
|
version (thus "3 A.M." appears as if "three A.M."); other numbers are sorted
|
|
numerically - thus "Zone 10" appears after "Zone 9", not after "Zone 1"; and
|
|
any bracketed text is ignored for alphabetisation purposes - so "(leaf) tea"
|
|
is alphabetised as if it were "tea".
|
|
</p>
|
|
|
|
<p class="commentary">Each headword has a "category". These categories must be defined in the
|
|
instructions file, using <span class="extract"><span class="extract-syntax">index:</span></span>. An index entry is defined by both headword
|
|
and category in combination, so "description" with category "property" is
|
|
different from "description" with category "standard", and they appear on
|
|
different lines in the index.
|
|
</p>
|
|
|
|
<p class="commentary">In terms of CSS, index entries occupy paragraphs of class <span class="extract"><span class="extract-syntax">indexentry</span></span>.
|
|
Text of an entry of category C is in a span of class <span class="extract"><span class="extract-syntax">indexC</span></span> (so for example,
|
|
an entry of category "name" is in a span of class <span class="extract"><span class="extract-syntax">indexname</span></span>). The links
|
|
are in spans of class <span class="extract"><span class="extract-syntax">indexlink</span></span> for the primary volume, <span class="extract"><span class="extract-syntax">indexlinkalt</span></span>
|
|
for the secondary.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b>If no categories are defined, there's no index. The instruction needed is:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> index: notation = name (options)</span>
|
|
</pre>
|
|
<p class="commentary">Notation is how indoc should recognise material to index; name is the name
|
|
of the category; the options, which are optional, specify anything special
|
|
about the category. There are three sorts of notation. The first is the
|
|
caret-and-brace form, for example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> index: ^{`headword} = name (invert)</span>
|
|
<span class="plain-syntax"> index: ^{headword} = standard</span>
|
|
</pre>
|
|
<p class="commentary">With these notations in place, a sentence in the documentation can be
|
|
marked up like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> The inventor of ^{literate programming} is ^{`Donald Knuth}.^^{archaisms}</span>
|
|
</pre>
|
|
<p class="commentary">Indexable terms always start with one or two carets and then material in
|
|
braces. One caret means the copy in braces is part of the book; two means
|
|
it isn't. Thus the above sentence typesets as
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> The inventor of literate programming is Donald Knuth.</span>
|
|
</pre>
|
|
<p class="commentary">A few points to note. The notations are sought in definition order, which
|
|
is why we defined ^{`headword} before ^{headword}. In general, the notation
|
|
has to be given in the form
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ^{LheadwordR}</span>
|
|
</pre>
|
|
<p class="commentary">where <span class="extract"><span class="extract-syntax">L</span></span> and <span class="extract"><span class="extract-syntax">R</span></span> are clumps of 0 or more characters; for example,
|
|
<span class="extract"><span class="extract-syntax">^{+headword+}</span></span> would be legal, as would <span class="extract"><span class="extract-syntax">^{''headword---}</span></span>. (It is best
|
|
to avoid underscores, asterisks, and of course braces.)
|
|
</p>
|
|
|
|
<p class="commentary">The catch-all <span class="extract"><span class="extract-syntax">^{headword}</span></span> notation has to refer to the category called
|
|
"standard", and should be defined last.
|
|
</p>
|
|
|
|
<p class="commentary">Indexing can be inserted into the body text of either volume, or in the
|
|
example files. However, they can't be placed in headings of any kind, or
|
|
in indented sample code paragraphs.
|
|
</p>
|
|
|
|
<p class="commentary">In general the index hyperlinks are to the top of the section cited, e.g., a
|
|
link to 3.2 goes to the top of section 3.2; or to the example cited, usually
|
|
at the bottom of some section; except that links to a phrase definition (in
|
|
Inform) go straight to its tinted box.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. </b>The options for categories are as follows:
|
|
</p>
|
|
|
|
<p class="commentary">Because the name category is marked <span class="extract"><span class="extract-syntax">(invert)</span></span>, its entries are inverted.
|
|
Thus <span class="extract"><span class="extract-syntax">^{Donald Knuth}</span></span> actually indexes as "Knuth, Donald", alphabetised
|
|
under K not D. Inversion is not performed if the text already contains a comma.
|
|
This can override wrong guesses. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Extensions are managed by ^{`Justin de Vesine}.</span>
|
|
</pre>
|
|
<p class="commentary">indexes "Vesine, Justin de" (filed under V); but
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Extensions are managed by Justin de Vesine.^^{`de Vesine, Justin}</span>
|
|
</pre>
|
|
<p class="commentary">indexes "de Vesine, Justin" (filed under D).
|
|
</p>
|
|
|
|
<p class="commentary">An option in double-quotes becomes a gloss text for the category. What
|
|
that means is that this text is added as a gloss, in small type, after
|
|
every index entry of that category, using the CSS span <span class="extract"><span class="extract-syntax">indexgloss</span></span>.
|
|
(By default, a category doesn't have a gloss.) Thus we might get index
|
|
entries like
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> grouping together something activity 18.14</span>
|
|
</pre>
|
|
<p class="commentary">with "activity" being the gloss text.
|
|
</p>
|
|
|
|
<p class="commentary">The option <span class="extract"><span class="extract-syntax">(bracketed)</span></span> causes the index entry to be rendered with bracketed
|
|
material in a CSS span called <span class="extract"><span class="extract-syntax">indexCbracketed</span></span>, where C is the category name.
|
|
For example, the Inform 7 Indoc instructions go on to say:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> css: span.indexphrasebracketed ++ {</span>
|
|
<span class="plain-syntax"> color: #8080ff;</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<p class="commentary">The practical effect is that the index entry:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (name of kind) after (enumerated value) phrase 11.18</span>
|
|
</pre>
|
|
<p class="commentary">has the bracketed parts tinted in a light blue for de-emphasis.
|
|
</p>
|
|
|
|
<p class="commentary">The option <span class="extract"><span class="extract-syntax">(under {lemma})</span></span> causes all entries for this category to be
|
|
subentries of <span class="extract"><span class="extract-syntax">{lemma}</span></span> - see below.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. </b>The second sort of notation is by documentation tag. An instruction like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> index: {act_} = activity ("activity")</span>
|
|
</pre>
|
|
<p class="commentary">This tells Indoc to pick up the tags used for links in the Inform app (see
|
|
above) and turn them into index entries too: in this case, any tag beginning
|
|
with <span class="extract"><span class="extract-syntax">act_</span></span> will be turned into an index entry of category "activity" for the
|
|
section in question, using the title of the section as the text of the entry,
|
|
flattened in case. The practical effect, then, is that all activities are
|
|
automatically indexed.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. </b>There are also two built-in sources of index entries, though they have
|
|
to be activated to appear. The Indoc instructions for Inform activate both:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> index: definition = phrase ("phrase") (bracketed)</span>
|
|
<span class="plain-syntax"> index: example = example ("example")</span>
|
|
</pre>
|
|
<p class="commentary">"definition" isn't really a notation; it tells indoc to make an index entry
|
|
out of every phrase definition in the manual. Similarly, "example" makes
|
|
an index entry for every example.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. </b>If an entry's text contains a colon (with substantive material either side),
|
|
that's taken as a marker that something is a subentry. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ^{reptiles: snakes}</span>
|
|
</pre>
|
|
<p class="commentary">creates something like
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> reptiles</span>
|
|
<span class="plain-syntax"> snakes 3.7</span>
|
|
</pre>
|
|
<p class="commentary">while typesetting just "snakes". For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "Why did it have to be ^{reptiles: snakes}?" mused Indy.</span>
|
|
</pre>
|
|
<p class="commentary">comes out as
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "Why did it have to be snakes?" mused Indy.</span>
|
|
</pre>
|
|
<p class="commentary">Sub-entries can be arbitrarily deep; there can be, but need not be, index
|
|
entries for the super-entry (in this case "reptiles").
|
|
</p>
|
|
|
|
<p class="commentary">We can also force every entry of a given category to fall as a subentry.
|
|
For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> index: ^{~headword} = reptilian (under {reptiles})</span>
|
|
</pre>
|
|
<p class="commentary">means that:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "Why did it have to be ^{~snakes}?" mused Indy.</span>
|
|
</pre>
|
|
<p class="commentary">once again makes "snakes" a subentry of "reptiles".
|
|
</p>
|
|
|
|
<p class="commentary">Note the difference between these two examples:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ^{people: `Donald Knuth}</span>
|
|
</pre>
|
|
<p class="commentary">makes
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> people (category "standard")</span>
|
|
<span class="plain-syntax"> Knuth, Donald (category "name")</span>
|
|
</pre>
|
|
<p class="commentary">whereas
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ^{`Donald Knuth: literate programming}</span>
|
|
</pre>
|
|
<p class="commentary">makes
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Knuth, Donald (category "name")</span>
|
|
<span class="plain-syntax"> literate programming (category "standard")</span>
|
|
</pre>
|
|
<p class="commentary">This is because Indoc parses <span class="extract"><span class="extract-syntax">{A:B}</span></span> as if it were parsing <span class="extract"><span class="extract-syntax">{A}</span></span> and <span class="extract"><span class="extract-syntax">{B}</span></span>
|
|
individually, to determine the categories of the superentry and subentry.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>§16. </b>Lastly, an entry in the form:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ^{reptiles <-- crocodiles <-- alligators}</span>
|
|
</pre>
|
|
<p class="commentary">tells indoc to index "reptiles" here, in the usual way, but also to add
|
|
cross-references "crocodiles, see reptiles" and "alligators, see reptiles"
|
|
at the appropriate places under C and A.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>§17. Example files. </b>Recall that each Example provided with the documentation — usually a
|
|
sample program — has its own source file. For example, in the standard
|
|
Inform repository, the example Alpaca Farm lives in:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Documentation/Examples/Alpaca.txt</span>
|
|
</pre>
|
|
<p class="commentary">Example files are just like volume files except that they open with a
|
|
special three-line header of metadata. In this example, it's:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> * New commands for old grammar</span>
|
|
<span class="plain-syntax"> (USE action which divines rational behavior for a wide range of possible nouns; Alpaca Farm)</span>
|
|
<span class="plain-syntax"> A generic USE action which behaves sensibly with a range of different objects.</span>
|
|
</pre>
|
|
<p class="commentary">Line 1 opens with one to four asterisks, which is the star rating (a measure
|
|
of difficulty/complexity), and then gives the section name to which it belongs.
|
|
This should be a section name in the primary volume, if there are two. (For
|
|
Inform, that's "Writing with Inform".)
|
|
</p>
|
|
|
|
<p class="commentary">Line 2 shows how to index the example, both thematically and, after the semicolon,
|
|
alphabetically.
|
|
</p>
|
|
|
|
<p class="commentary">Line 3 is the "strapline" shown under the example title in the documentation.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>§18. </b>The above metadata is not quite enough to locate the example, because it
|
|
only gives a position in the primary volume (e.g., "Writing with Inform").
|
|
Where should the example go in the secondary (e.g., "The Inform Recipe Book")?
|
|
</p>
|
|
|
|
<p class="commentary">The answer is provided by the special file
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Documentation/Examples/(Recipes).txt</span>
|
|
</pre>
|
|
<p class="commentary">which is not an example, but a list of examples under chapter and section
|
|
names in the Recipe Book. This is fairly self-explanatory, but note that
|
|
examples appear not under their named ("Alpaca Farm") but under their
|
|
thematic descriptions ("USE action which divines rational behavior for a
|
|
wide range of possible nouns") — the point of which being that the Recipe
|
|
Book is organised by theme.
|
|
</p>
|
|
|
|
<p class="commentary">There's one special notation, for use at the top of the recipes file:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Going Going == OMIT</span>
|
|
</pre>
|
|
<p class="commentary">This says that a named example, here "Going Going", should be omitted
|
|
altogether from the Recipe Book. (Inform omits about 12 of these.)
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-vai.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-iti.html">iti</a></li><li class="progresssection"><a href="M-vai.html">vai</a></li><li class="progresscurrent">dm</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-rc.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|