2019-03-17 14:40:57 +02:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
< html >
< head >
2020-04-14 19:56:54 +03:00
< title > Documentation Markup< / title >
2020-05-03 03:20:55 +03:00
< link href = "../docs-assets/Breadcrumbs.css" rel = "stylesheet" rev = "stylesheet" type = "text/css" >
2020-03-19 02:11:25 +02:00
< meta name = "viewport" content = "width=device-width initial-scale=1" >
2019-03-17 14:40:57 +02:00
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" >
< meta http-equiv = "Content-Language" content = "en-gb" >
2020-05-03 03:01:21 +03:00
2020-05-03 03:20:55 +03:00
< 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" >
2020-04-14 19:56:54 +03:00
2019-03-17 14:40:57 +02:00
< / head >
2020-05-03 03:01:21 +03:00
< body class = "commentary-font" >
2020-03-19 02:11:25 +02:00
< nav role = "navigation" >
2020-04-14 19:56:54 +03:00
< h1 > < a href = "../index.html" >
2020-05-03 18:34:53 +03:00
< img src = "../docs-assets/Inform.png" height = 72" >
2020-04-14 19:56:54 +03:00
< / a > < / h1 >
< ul > < li > < a href = "../compiler.html" > compiler tools< / a > < / li >
< li > < a href = "../other.html" > other tools< / a > < / li >
2020-03-19 02:11:25 +02:00
< li > < a href = "../extensions.html" > extensions and kits< / a > < / li >
< li > < a href = "../units.html" > unit test tools< / a > < / li >
2020-04-14 19:56:54 +03:00
< / ul > < h2 > Other Tools< / h2 > < ul >
2020-03-19 02:11:25 +02:00
< li > < a href = "../inblorb/index.html" > inblorb< / a > < / li >
2020-04-14 19:56:54 +03:00
< li > < a href = "index.html" > < span class = "selectedlink" > indoc< / span > < / a > < / li >
2020-03-19 02:11:25 +02:00
< li > < a href = "../inpolicy/index.html" > inpolicy< / a > < / li >
< li > < a href = "../inrtps/index.html" > inrtps< / a > < / li >
2020-04-14 19:56:54 +03:00
< / ul > < h2 > Foundation< / h2 > < ul >
2020-03-19 02:11:25 +02:00
< li > < a href = "../../../inweb/docs/foundation-module/index.html" > foundation< / a > < / li >
2020-04-14 19:56:54 +03:00
< / ul >
2020-03-19 02:11:25 +02:00
< / nav >
< main role = "main" >
2020-05-03 03:01:21 +03:00
<!-- 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 >
2019-03-17 14:40:57 +02:00
2020-04-16 01:49:59 +03:00
< 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" >
2019-03-17 14:40:57 +02:00
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
for the markup notations described below, these really are plain text,
using skipped lines as paragraph breaks, and tabs for indented quotations:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2020-04-08 01:02:44 +03:00
2020-05-03 03:01:21 +03:00
< 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 >
2020-04-08 01:02:44 +03:00
2020-05-03 03:01:21 +03:00
< span class = "plain-syntax" > The second para begins here, after the< / span >
< span class = "plain-syntax" > skipped line.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Note that line breaks in quotations are respected, whereas in regular
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > For example:< / span >
2020-04-08 01:02:44 +03:00
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > "Quotations", as this suggests, are often in fact code examples for some
2019-03-17 14:40:57 +02:00
programming language.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
included in documentation; but the syntax < b> Bold< /n> and < i> Italic< /i> is
an exception.
< / p >
2020-08-27 17:50:24 +03:00
< 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:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > The top line is the title for the table, and then tab-delimited columns follow.
2019-03-17 14:40:57 +02:00
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
into sections. A line in the form:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > [Chapter: CHAPTERTITLE] SECTIONTITLE< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > begins a new chapter, and simultaneously begins its first section; the first
2019-03-17 14:40:57 +02:00
line of a volume file must be of this form. For example,
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > [Chapter: Things] Descriptions< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > When it's time for a new section within the same chapter, the simpler form:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > [x] SECTIONTITLE< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > is used. Note that although chapters and sections are both numbered, this
2019-03-17 14:40:57 +02:00
numbering is automatically applied by Indoc, and does not appear in the source.
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > The final paragraph of a section is allowed to take a special form:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > (See REFERENCE for PURPOSE.)< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > For example,
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Here, the < span class = "extract" > < span class = "extract-syntax" > REFERENCE< / span > < / span > "Text with substitutions" is to another section in
2019-03-17 14:40:57 +02:00
the volume, having that title. Indoc will make this into a suitable link
in the generated HTML.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
generated documentation only for targets which match this context. A
2020-05-03 03:01:21 +03:00
context can be just a symbol created by < span class = "extract" > < span class = "extract-syntax" > declare:< / span > < / span > in the instructions
2019-03-17 14:40:57 +02:00
file, so for example:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > would be included only if the instruction < span class = "extract" > < span class = "extract-syntax" > declare: Linux< / span > < / span > had been made
2019-03-17 14:40:57 +02:00
for the current target.
< / p >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
in that order. The simplest case is
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
examples would be:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > {^alpha,beta+gamma:}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
are declared; and
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
declared.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > A quotation beginning with < span class = "extract" > < span class = "extract-syntax" > {**}< / span > < / span > is a continuation of the previous
2019-03-17 14:40:57 +02:00
paste-this-in quotation.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
marked as in this example:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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,
2019-03-17 14:40:57 +02:00
are invisible in the HTML output, but are used in the cross-referencing
material which Indoc produces for the benefit of Inform.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
inside the Inform app. We can prepare for this by tagging the opening line
of a section like so:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > [x] Rooms and the map {kind_room} {MAP} {PM_SameKindEquated}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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 > .
2019-03-17 14:40:57 +02:00
These are used by Inform for the helpful links in the Index or in problem
2020-05-03 03:01:21 +03:00
messages: for example, if the user generates the problem < span class = "extract" > < span class = "extract-syntax" > PM_SameKindEquated< / span > < / span >
2019-03-17 14:40:57 +02:00
(this is its internal designation, of course), a link will appear, and it
will be to this section, "Rooms and the map".
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > I am the ^{walrus}.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > becomes simply
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > I am the walrus.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
index entry is invisible in the text itself, and only the position is
marked. Thus
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > I am the ^{walrus}.^^{Beatles}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > A much more detailed description now follows.
2019-03-17 14:40:57 +02:00
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Headwords are alphabetized in a way which excludes initial "a", "an" or "the";
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
for the secondary.
< / p >
2020-08-27 17:50:24 +03:00
< 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:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > index: notation = name (options)< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Notation is how indoc should recognise material to index; name is the name
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > With these notations in place, a sentence in the documentation can be
2019-03-17 14:40:57 +02:00
marked up like so:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > The inventor of ^{literate programming} is ^{`Donald Knuth}.^^{archaisms}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Indexable terms always start with one or two carets and then material in
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > The inventor of literate programming is Donald Knuth.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > A few points to note. The notations are sought in definition order, which
2019-03-17 14:40:57 +02:00
is why we defined ^{`headword} before ^{headword}. In general, the notation
has to be given in the form
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > ^{LheadwordR}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
to avoid underscores, asterisks, and of course braces.)
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > The catch-all < span class = "extract" > < span class = "extract-syntax" > ^{headword}< / span > < / span > notation has to refer to the category called
2019-03-17 14:40:57 +02:00
"standard", and should be defined last.
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Indexing can be inserted into the body text of either volume, or in the
2019-03-17 14:40:57 +02:00
example files. However, they can't be placed in headings of any kind, or
in indented sample code paragraphs.
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > In general the index hyperlinks are to the top of the section cited, e.g., a
2019-03-17 14:40:57 +02:00
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 >
2020-08-27 17:50:24 +03:00
< p class = "commentary firstcommentary" > < a id = "SP12" class = "paragraph-anchor" > < / a > < b > § 12. < / b > The options for categories are as follows:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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
2019-03-17 14:40:57 +02:00
under K not D. Inversion is not performed if the text already contains a comma.
This can override wrong guesses. Thus:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > Extensions are managed by ^{`Justin de Vesine}.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > indexes "Vesine, Justin de" (filed under V); but
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > Extensions are managed by Justin de Vesine.^^{`de Vesine, Justin}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > indexes "de Vesine, Justin" (filed under D).
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > An option in double-quotes becomes a gloss text for the category. What
2019-03-17 14:40:57 +02:00
that means is that this text is added as a gloss, in small type, after
2020-05-03 03:01:21 +03:00
every index entry of that category, using the CSS span < span class = "extract" > < span class = "extract-syntax" > indexgloss< / span > < / span > .
2019-03-17 14:40:57 +02:00
(By default, a category doesn't have a gloss.) Thus we might get index
entries like
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > grouping together something activity 18.14< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > with "activity" being the gloss text.
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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.
2019-03-17 14:40:57 +02:00
For example, the Inform 7 Indoc instructions go on to say:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > The practical effect is that the index entry:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > (name of kind) after (enumerated value) phrase 11.18< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > has the bracketed parts tinted in a light blue for de-emphasis.
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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.
2019-03-17 14:40:57 +02:00
< / p >
2020-08-27 17:50:24 +03:00
< 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:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > index: {act_} = activity ("activity")< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > This tells Indoc to pick up the tags used for links in the Inform app (see
2019-03-17 14:40:57 +02:00
above) and turn them into index entries too: in this case, any tag beginning
2020-05-03 03:01:21 +03:00
with < span class = "extract" > < span class = "extract-syntax" > act_< / span > < / span > will be turned into an index entry of category "activity" for the
2019-03-17 14:40:57 +02:00
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 >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
to be activated to appear. The Indoc instructions for Inform activate both:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > "definition" isn't really a notation; it tells indoc to make an index entry
2019-03-17 14:40:57 +02:00
out of every phrase definition in the manual. Similarly, "example" makes
an index entry for every example.
< / p >
2020-08-27 17:50:24 +03:00
< 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),
2019-03-17 14:40:57 +02:00
that's taken as a marker that something is a subentry. Thus:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > ^{reptiles: snakes}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > creates something like
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > reptiles< / span >
< span class = "plain-syntax" > snakes 3.7< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > while typesetting just "snakes". For example,
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > "Why did it have to be ^{reptiles: snakes}?" mused Indy.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > comes out as
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > "Why did it have to be snakes?" mused Indy.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Sub-entries can be arbitrarily deep; there can be, but need not be, index
2019-03-17 14:40:57 +02:00
entries for the super-entry (in this case "reptiles").
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > We can also force every entry of a given category to fall as a subentry.
2019-03-17 14:40:57 +02:00
For example:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > index: ^{~headword} = reptilian (under {reptiles})< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > means that:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > "Why did it have to be ^{~snakes}?" mused Indy.< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > once again makes "snakes" a subentry of "reptiles".
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Note the difference between these two examples:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > ^{people: `Donald Knuth}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > makes
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > whereas
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > ^{`Donald Knuth: literate programming}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > makes
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
individually, to determine the categories of the superentry and subentry.
< / p >
2020-08-27 17:50:24 +03:00
< p class = "commentary firstcommentary" > < a id = "SP16" class = "paragraph-anchor" > < / a > < b > § 16. < / b > Lastly, an entry in the form:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > ^{reptiles < -- crocodiles < -- alligators}< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > tells indoc to index "reptiles" here, in the usual way, but also to add
2019-03-17 14:40:57 +02:00
cross-references "crocodiles, see reptiles" and "alligators, see reptiles"
at the appropriate places under C and A.
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
sample program — has its own source file. For example, in the standard
Inform repository, the example Alpaca Farm lives in:
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > Documentation/Examples/Alpaca.txt< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Example files are just like volume files except that they open with a
2019-03-17 14:40:57 +02:00
special three-line header of metadata. In this example, it's:
< / p >
2020-05-03 03:01:21 +03:00
< 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 >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Line 1 opens with one to four asterisks, which is the star rating (a measure
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Line 2 shows how to index the example, both thematically and, after the semicolon,
2019-03-17 14:40:57 +02:00
alphabetically.
< / p >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > Line 3 is the "strapline" shown under the example title in the documentation.
2019-03-17 14:40:57 +02:00
< / p >
2020-08-27 17:50:24 +03:00
< 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
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > The answer is provided by the special file
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > Documentation/Examples/(Recipes).txt< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > which is not an example, but a list of examples under chapter and section
2019-03-17 14:40:57 +02:00
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 >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > There's one special notation, for use at the top of the recipes file:
2019-03-17 14:40:57 +02:00
< / p >
2020-05-03 03:01:21 +03:00
< pre class = "displayed-code all-displayed-code code-font" >
< span class = "plain-syntax" > Going Going == OMIT< / span >
2019-03-17 14:40:57 +02:00
< / pre >
2020-05-03 03:01:21 +03:00
< p class = "commentary" > This says that a named example, here "Going Going", should be omitted
2019-03-17 14:40:57 +02:00
altogether from the Recipe Book. (Inform omits about 12 of these.)
< / p >
2020-05-03 03:01:21 +03:00
< 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 -->
2020-03-19 02:11:25 +02:00
< / main >
2019-03-17 14:40:57 +02:00
< / body >
< / html >
