mirror of
https://github.com/ganelson/inform.git
synced 2024-07-08 01:54:21 +03:00
718 lines
26 KiB
HTML
718 lines
26 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>P/vai</title>
|
|
<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>
|
|
|
|
<!--Weave of 'P/dm' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">★</a></li><li><a href="index.html">indoc 4</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>Documentation Markup</b></li></ul><p class="purpose">How to mark up the plain-text source for Inform documentation.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. Volume files</a></li><li><a href="#SP6">§6. Inform-specific markup</a></li><li><a href="#SP9">§9. Indexing</a></li><li><a href="#SP17">§17. Example files</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">This is a paragraph of some text, which</span>
|
|
<span class="plain">extends over perhaps many lines. All of the</span>
|
|
<span class="plain">standard letters are allowed:</span>
|
|
|
|
<span class="plain"> The quick brown fox jumped over the lazy dog.</span>
|
|
<span class="plain"> Jinxed wizards pluck ivy from my quilt.</span>
|
|
<span class="plain"> Jackdaws love my big sphinx of quartz.</span>
|
|
|
|
<span class="plain">The second para begins here, after the</span>
|
|
<span class="plain">skipped line.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">For example:</span>
|
|
|
|
<span class="plain"> Instead of waiting when the prevailing wind is northwest:</span>
|
|
<span class="plain"> say "A fresh gust of wind bowls you over.";</span>
|
|
<span class="plain"> now the prevailing wind is east.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">"Quotations", as this suggests, are often in fact code examples for some
|
|
programming language.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></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="inwebparagraph"><a id="SP3"></a><b>§3. </b>Tables are formatted automatically whenever Indoc sees a pattern like this:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain"> {*}Table 2 - Selected Elements</span>
|
|
<span class="plain"> Element Symbol Atomic number</span>
|
|
<span class="plain"> "Hydrogen" "H" 1</span>
|
|
<span class="plain"> "Iron" "Fe" 26</span>
|
|
<span class="plain"> "Zinc" "Zn" 30</span>
|
|
<span class="plain"> "Uranium" "U" 92</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The top line is the title for the table, and then tab-delimited columns follow.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. </b>Recall that volumes are divided into chapters, which are themselves divided
|
|
into sections. A line in the form:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[Chapter: CHAPTERTITLE] SECTIONTITLE</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[Chapter: Things] Descriptions</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">When it's time for a new section within the same chapter, the simpler form:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[x] SECTIONTITLE</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">The final paragraph of a section is allowed to take a special form:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">(See REFERENCE for PURPOSE.)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">(See Text with substitutions for more on varying what is printed.)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Here, the <code class="display"><span class="extract">REFERENCE</span></code> "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="inwebparagraph"><a id="SP5"></a><b>§5. </b>When a paragraph begins with <code class="display"><span class="extract">{CONTEXT:}</span></code>, it is included in the
|
|
generated documentation only for targets which match this context. A
|
|
context can be just a symbol created by <code class="display"><span class="extract">declare:</span></code> in the instructions
|
|
file, so for example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">{Linux:}The top secret DRM decoder ring is not included under Debian...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">would be included only if the instruction <code class="display"><span class="extract">declare: Linux</span></code> had been made
|
|
for the current target.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Contexts can however be compound, using the unary operator <code class="display"><span class="extract">^</span></code> (negation),
|
|
the binary <code class="display"><span class="extract">+</span></code> (conjunction), and binary <code class="display"><span class="extract">,</span></code> (disjunction), which associate
|
|
in that order. The simplest case is
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">{^Linux:}The top secret DRM decoder ring is in the Goodies folder...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">which is included if and only if <code class="display"><span class="extract">Linux</span></code> has not been declared. More elaborate
|
|
examples would be:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">{^alpha,beta+gamma:}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">which is true if either <code class="display"><span class="extract">alpha</span></code> is undeclared, or if both <code class="display"><span class="extract">beta</span></code> and <code class="display"><span class="extract">gamma</span></code>
|
|
are declared; and
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">{^(alpha,beta)+gamma:}</span>
|
|
<span class="plain">{^alpha+^beta+gamma:}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">which are both true if <code class="display"><span class="extract">alpha</span></code> and <code class="display"><span class="extract">beta</span></code> are undeclared but <code class="display"><span class="extract">gamma</span></code> is
|
|
declared.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§6. Inform-specific markup. </b>A quotation beginning with <code class="display"><span class="extract">{*}</span></code> 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="inwebparagraph">A quotation beginning with <code class="display"><span class="extract">{**}</span></code> is a continuation of the previous
|
|
paste-this-in quotation.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP7"></a><b>§7. </b>In Inform documentation, the formal specification of a phrase can be
|
|
marked as in this example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">{defn ph_randomdesc}a/-- random (description of values) ... value</span>
|
|
<span class="plain">This phrase makes a uniformly random choice...</span>
|
|
<span class="plain">...the result is the special value "nothing".</span>
|
|
<span class="plain">{end}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The markers <code class="display"><span class="extract">{defn ph_randomdesc}</span></code> and <code class="display"><span class="extract">{end}</span></code>, 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="inwebparagraph"><a id="SP8"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[x] Rooms and the map {kind_room} {MAP} {PM_SameKindEquated}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This applies three tags to the section: <code class="display"><span class="extract">kind_room</span></code>, <code class="display"><span class="extract">MAP</span></code> and <code class="display"><span class="extract">PM_SameKindEquated</span></code>.
|
|
These are used by Inform for the helpful links in the Index or in problem
|
|
messages: for example, if the user generates the problem <code class="display"><span class="extract">PM_SameKindEquated</span></code>
|
|
(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="inwebparagraph"><a id="SP9"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">I am the ^{walrus}.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">becomes simply
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">I am the walrus.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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 <code class="display"><span class="extract">^</span></code> is used, the
|
|
index entry is invisible in the text itself, and only the position is
|
|
marked. Thus
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">I am the ^{walrus}.^^{Beatles}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">A much more detailed description now follows.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP10"></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="inwebparagraph">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="inwebparagraph">Each headword has a "category". These categories must be defined in the
|
|
instructions file, using <code class="display"><span class="extract">index:</span></code>. 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="inwebparagraph">In terms of CSS, index entries occupy paragraphs of class <code class="display"><span class="extract">indexentry</span></code>.
|
|
Text of an entry of category C is in a span of class <code class="display"><span class="extract">indexC</span></code> (so for example,
|
|
an entry of category "name" is in a span of class <code class="display"><span class="extract">indexname</span></code>). The links
|
|
are in spans of class <code class="display"><span class="extract">indexlink</span></code> for the primary volume, <code class="display"><span class="extract">indexlinkalt</span></code>
|
|
for the secondary.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP11"></a><b>§11. </b>If no categories are defined, there's no index. The instruction needed is:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">index: notation = name (options)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">index: ^{`headword} = name (invert)</span>
|
|
<span class="plain">index: ^{headword} = standard</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">With these notations in place, a sentence in the documentation can be
|
|
marked up like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">The inventor of ^{literate programming} is ^{`Donald Knuth}.^^{archaisms}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">The inventor of literate programming is Donald Knuth.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">^{LheadwordR}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">where <code class="display"><span class="extract">L</span></code> and <code class="display"><span class="extract">R</span></code> are clumps of 0 or more characters; for example,
|
|
<code class="display"><span class="extract">^{+headword+}</span></code> would be legal, as would <code class="display"><span class="extract">^{''headword---}</span></code>. (It is best
|
|
to avoid underscores, asterisks, and of course braces.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The catch-all <code class="display"><span class="extract">^{headword}</span></code> notation has to refer to the category called
|
|
"standard", and should be defined last.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">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="inwebparagraph"><a id="SP12"></a><b>§12. </b>The options for categories are as follows:
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Because the name category is marked <code class="display"><span class="extract">(invert)</span></code>, its entries are inverted.
|
|
Thus <code class="display"><span class="extract">^{Donald Knuth}</span></code> 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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Extensions are managed by ^{`Justin de Vesine}.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">indexes "Vesine, Justin de" (filed under V); but
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Extensions are managed by Justin de Vesine.^^{`de Vesine, Justin}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">indexes "de Vesine, Justin" (filed under D).
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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 <code class="display"><span class="extract">indexgloss</span></code>.
|
|
(By default, a category doesn't have a gloss.) Thus we might get index
|
|
entries like
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">grouping together something activity 18.14</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">with "activity" being the gloss text.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The option <code class="display"><span class="extract">(bracketed)</span></code> causes the index entry to be rendered with bracketed
|
|
material in a CSS span called <code class="display"><span class="extract">indexCbracketed</span></code>, where C is the category name.
|
|
For example, the Inform 7 Indoc instructions go on to say:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">css: span.indexphrasebracketed ++ {</span>
|
|
<span class="plain"> color: #8080ff;</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The practical effect is that the index entry:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">(name of kind) after (enumerated value) phrase 11.18</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">has the bracketed parts tinted in a light blue for de-emphasis.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The option <code class="display"><span class="extract">(under {lemma})</span></code> causes all entries for this category to be
|
|
subentries of <code class="display"><span class="extract">{lemma}</span></code> - see below.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP13"></a><b>§13. </b>The second sort of notation is by documentation tag. An instruction like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">index: {act_} = activity ("activity")</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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 <code class="display"><span class="extract">act_</span></code> 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="inwebparagraph"><a id="SP14"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">index: definition = phrase ("phrase") (bracketed)</span>
|
|
<span class="plain">index: example = example ("example")</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">"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="inwebparagraph"><a id="SP15"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">^{reptiles: snakes}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">creates something like
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">reptiles</span>
|
|
<span class="plain"> snakes 3.7</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">while typesetting just "snakes". For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">"Why did it have to be ^{reptiles: snakes}?" mused Indy.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">comes out as
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">"Why did it have to be snakes?" mused Indy.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">We can also force every entry of a given category to fall as a subentry.
|
|
For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">index: ^{~headword} = reptilian (under {reptiles})</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">means that:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">"Why did it have to be ^{~snakes}?" mused Indy.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">once again makes "snakes" a subentry of "reptiles".
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Note the difference between these two examples:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">^{people: `Donald Knuth}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">makes
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">people (category "standard")</span>
|
|
<span class="plain"> Knuth, Donald (category "name")</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">whereas
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">^{`Donald Knuth: literate programming}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">makes
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Knuth, Donald (category "name")</span>
|
|
<span class="plain"> literate programming (category "standard")</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This is because Indoc parses <code class="display"><span class="extract">{A:B}</span></code> as if it were parsing <code class="display"><span class="extract">{A}</span></code> and <code class="display"><span class="extract">{B}</span></code>
|
|
individually, to determine the categories of the superentry and subentry.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP16"></a><b>§16. </b>Lastly, an entry in the form:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">^{reptiles <-- crocodiles <-- alligators}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph"><a id="SP17"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Documentation/Examples/Alpaca.txt</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">* New commands for old grammar</span>
|
|
<span class="plain">(USE action which divines rational behavior for a wide range of possible nouns; Alpaca Farm)</span>
|
|
<span class="plain">A generic USE action which behaves sensibly with a range of different objects.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">Line 2 shows how to index the example, both thematically and, after the semicolon,
|
|
alphabetically.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Line 3 is the "strapline" shown under the example title in the documentation.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP18"></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="inwebparagraph">The answer is provided by the special file
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Documentation/Examples/(Recipes).txt</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">There's one special notation, for use at the top of the recipes file:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Going Going == OMIT</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This says that a named example, here "Going Going", should be omitted
|
|
altogether from the Recipe Book. (Inform omits about 12 of these.)
|
|
</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="P-vai.html">Back to 'Volumes and Instructions'</a></li><li><i>(This section ends Preliminaries.)</i></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</body>
|
|
</html>
|
|
|