<ulclass="crumbs"><li><ahref="../webs.html">Source</a></li><li><ahref="../other.html">Other Tools</a></li><li><ahref="index.html">indoc</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Documentation Markup</b></li></ul><pclass="purpose">How to mark up the plain-text source for Inform documentation.</p>
<pclass="inwebparagraph">When it's time for a new section within the same chapter, the simpler form:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">[x] SECTIONTITLE</span>
</pre>
<pclass="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>
<pclass="inwebparagraph">The final paragraph of a section is allowed to take a special form:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">(See REFERENCE for PURPOSE.)</span>
</pre>
<pclass="inwebparagraph">For example,
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">(See Text with substitutions for more on varying what is printed.)</span>
</pre>
<pclass="inwebparagraph">Here, the <codeclass="display"><spanclass="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>
<pclass="inwebparagraph"><aid="SP5"></a><b>§5. </b>When a paragraph begins with <codeclass="display"><spanclass="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 <codeclass="display"><spanclass="extract">declare:</span></code> in the instructions
file, so for example:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">{Linux:}The top secret DRM decoder ring is not included under Debian...</span>
</pre>
<pclass="inwebparagraph">would be included only if the instruction <codeclass="display"><spanclass="extract">declare: Linux</span></code> had been made
for the current target.
</p>
<pclass="inwebparagraph">Contexts can however be compound, using the unary operator <codeclass="display"><spanclass="extract">^</span></code> (negation),
the binary <codeclass="display"><spanclass="extract">+</span></code> (conjunction), and binary <codeclass="display"><spanclass="extract">,</span></code> (disjunction), which associate
in that order. The simplest case is
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">{^Linux:}The top secret DRM decoder ring is in the Goodies folder...</span>
</pre>
<pclass="inwebparagraph">which is included if and only if <codeclass="display"><spanclass="extract">Linux</span></code> has not been declared. More elaborate
examples would be:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">{^alpha,beta+gamma:}</span>
</pre>
<pclass="inwebparagraph">which is true if either <codeclass="display"><spanclass="extract">alpha</span></code> is undeclared, or if both <codeclass="display"><spanclass="extract">beta</span></code> and <codeclass="display"><spanclass="extract">gamma</span></code>
are declared; and
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">{^(alpha,beta)+gamma:}</span>
<spanclass="plain">{^alpha+^beta+gamma:}</span>
</pre>
<pclass="inwebparagraph">which are both true if <codeclass="display"><spanclass="extract">alpha</span></code> and <codeclass="display"><spanclass="extract">beta</span></code> are undeclared but <codeclass="display"><spanclass="extract">gamma</span></code> is
declared.
</p>
<pclass="inwebparagraph"><aid="SP6"></a><b>§6. Inform-specific markup. </b>A quotation beginning with <codeclass="display"><spanclass="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>
<pclass="inwebparagraph">A quotation beginning with <codeclass="display"><spanclass="extract">{**}</span></code> is a continuation of the previous
paste-this-in quotation.
</p>
<pclass="inwebparagraph"><aid="SP7"></a><b>§7. </b>In Inform documentation, the formal specification of a phrase can be
marked as in this example:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">{defn ph_randomdesc}a/-- random (description of values) ... value</span>
<spanclass="plain">This phrase makes a uniformly random choice...</span>
<spanclass="plain">...the result is the special value "nothing".</span>
<spanclass="plain">{end}</span>
</pre>
<pclass="inwebparagraph">The markers <codeclass="display"><spanclass="extract">{defn ph_randomdesc}</span></code> and <codeclass="display"><spanclass="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>
<pclass="inwebparagraph"><aid="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">[x] Rooms and the map {kind_room} {MAP} {PM_SameKindEquated}</span>
</pre>
<pclass="inwebparagraph">This applies three tags to the section: <codeclass="display"><spanclass="extract">kind_room</span></code>, <codeclass="display"><spanclass="extract">MAP</span></code> and <codeclass="display"><spanclass="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 <codeclass="display"><spanclass="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>
<pclass="inwebparagraph"><aid="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">I am the ^{walrus}.</span>
</pre>
<pclass="inwebparagraph">becomes simply
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">I am the walrus.</span>
</pre>
<pclass="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 <codeclass="display"><spanclass="extract">^</span></code> is used, the
index entry is invisible in the text itself, and only the position is
marked. Thus
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">I am the ^{walrus}.^^{Beatles}</span>
</pre>
<pclass="inwebparagraph">A much more detailed description now follows.
</p>
<pclass="inwebparagraph"><aid="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>
<pclass="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>
<pclass="inwebparagraph">Each headword has a "category". These categories must be defined in the
instructions file, using <codeclass="display"><spanclass="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>
<pclass="inwebparagraph">In terms of CSS, index entries occupy paragraphs of class <codeclass="display"><spanclass="extract">indexentry</span></code>.
Text of an entry of category C is in a span of class <codeclass="display"><spanclass="extract">indexC</span></code> (so for example,
an entry of category "name" is in a span of class <codeclass="display"><spanclass="extract">indexname</span></code>). The links
are in spans of class <codeclass="display"><spanclass="extract">indexlink</span></code> for the primary volume, <codeclass="display"><spanclass="extract">indexlinkalt</span></code>
for the secondary.
</p>
<pclass="inwebparagraph"><aid="SP11"></a><b>§11. </b>If no categories are defined, there's no index. The instruction needed is:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">index: notation = name (options)</span>
</pre>
<pclass="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">index: ^{`headword} = name (invert)</span>
<pclass="inwebparagraph">With these notations in place, a sentence in the documentation can be
marked up like so:
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">The inventor of ^{literate programming} is ^{`Donald Knuth}.^^{archaisms}</span>
</pre>
<pclass="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">The inventor of literate programming is Donald Knuth.</span>
</pre>
<pclass="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">^{LheadwordR}</span>
</pre>
<pclass="inwebparagraph">where <codeclass="display"><spanclass="extract">L</span></code> and <codeclass="display"><spanclass="extract">R</span></code> are clumps of 0 or more characters; for example,
<codeclass="display"><spanclass="extract">^{+headword+}</span></code> would be legal, as would <codeclass="display"><spanclass="extract">^{''headword---}</span></code>. (It is best
to avoid underscores, asterisks, and of course braces.)
</p>
<pclass="inwebparagraph">The catch-all <codeclass="display"><spanclass="extract">^{headword}</span></code> notation has to refer to the category called
"standard", and should be defined last.
</p>
<pclass="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>
<pclass="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>
<pclass="inwebparagraph"><aid="SP12"></a><b>§12. </b>The options for categories are as follows:
</p>
<pclass="inwebparagraph">Because the name category is marked <codeclass="display"><spanclass="extract">(invert)</span></code>, its entries are inverted.
Thus <codeclass="display"><spanclass="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>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">Extensions are managed by ^{`Justin de Vesine}.</span>
</pre>
<pclass="inwebparagraph">indexes "Vesine, Justin de" (filed under V); but
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">Extensions are managed by Justin de Vesine.^^{`de Vesine, Justin}</span>
</pre>
<pclass="inwebparagraph">indexes "de Vesine, Justin" (filed under D).
</p>
<pclass="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 <codeclass="display"><spanclass="extract">indexgloss</span></code>.
(By default, a category doesn't have a gloss.) Thus we might get index
entries like
</p>
<pclass="inwebparagraph"></p>
<preclass="display">
<spanclass="plain">grouping together something activity 18.14</span>
</pre>
<pclass="inwebparagraph">with "activity" being the gloss text.
</p>
<pclass="inwebparagraph">The option <codeclass="display"><spanclass="extract">(bracketed)</span></code> causes the index entry to be rendered with bracketed
material in a CSS span called <codeclass="display"><spanclass="extract">indexCbracketed</span></code>, where C is the category name.
For example, the Inform 7 Indoc instructions go on to say:
<pclass="inwebparagraph">This is because Indoc parses <codeclass="display"><spanclass="extract">{A:B}</span></code> as if it were parsing <codeclass="display"><spanclass="extract">{A}</span></code> and <codeclass="display"><spanclass="extract">{B}</span></code>
individually, to determine the categories of the superentry and subentry.
</p>
<pclass="inwebparagraph"><aid="SP16"></a><b>§16. </b>Lastly, an entry in the form:
<ulclass="toc"><li><ahref="M-vai.html">Back to 'Volumes and Instructions'</a></li><li><ahref="M-rc.html">Continue with 'Reference Card'</a></li></ul><hrclass="tocbar">