Skip to content

Commit aeb8150

Browse files
authored
Add Glossary
First Glossary draft with an initial entry (*stropping*) and some commented-out pending entries TBD later on (Closes #54). Update contents of "§4.2. Words, Identifiers and Names": * Add "Stropping" sub-section. * Add `stropping` anchor. * Add `stropping` Index entry. * Revise and improve contents of this section: * More examples. * Extra admonitions. * Polish text. Clean-up, polish and update README files in Alan Manual directory. Referenced Issues: #36, #50, #54, asciidoctor/asciidoctor#3248.
2 parents dfa4897 + e31cd9b commit aeb8150

File tree

7 files changed

+699
-175
lines changed

7 files changed

+699
-175
lines changed

manual/README.md

+296-133
Large diffs are not rendered by default.

manual/manual.asciidoc

+8-6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:doctitle: The ALAN Adventure Language Reference Manual
2-
:revnumber: 0.1.92-PreReleaseBeta7
3-
:revdate: August 7, 2019
2+
:revnumber: 0.1.96-PreReleaseBeta7
3+
:revdate: September 1, 2019
44
:revremark: AsciiDoc conversion work
55
:doctype: book
66
:encoding: utf-8
@@ -131,18 +131,20 @@ include::manual_15.asciidoc[]
131131
// ==============================
132132
include::manual_16.asciidoc[]
133133

134+
:sectnums!:
135+
136+
// Glossary
137+
// ========
138+
include::manual_17.asciidoc[]
139+
134140
// Index
135141
// =====
136142
// We'll exclude it from HTML5 documents since that backend doesn't support it:
137143
ifeval::["{backend}" != "html5"]
138144

139-
:sectnums!:
140-
141145
[index]
142146
= Index
143147

144-
:sectnums:
145-
146148
endif::[]
147149

148150
// ...

manual/manual.html

+132-16
Original file line numberDiff line numberDiff line change
@@ -441,8 +441,8 @@
441441
<div id="header">
442442
<h1>The ALAN Adventure Language Reference Manual</h1>
443443
<div class="details">
444-
<span id="revnumber">version 0.1.92-PreReleaseBeta7,</span>
445-
<span id="revdate">August 7, 2019</span>
444+
<span id="revnumber">version 0.1.96-PreReleaseBeta7,</span>
445+
<span id="revdate">September 1, 2019</span>
446446
<br><span id="revremark">AsciiDoc conversion work</span>
447447
</div>
448448
<div id="toc" class="toc2">
@@ -715,7 +715,13 @@ <h1>The ALAN Adventure Language Reference Manual</h1>
715715
<li><a href="#_lexical_definitions">4. Lexical Definitions</a>
716716
<ul class="sectlevel2">
717717
<li><a href="#_comments">4.1. Comments</a></li>
718-
<li><a href="#_words_identifiers_and_names">4.2. Words, Identifiers and Names</a></li>
718+
<li><a href="#_words_identifiers_and_names">4.2. Words, Identifiers and Names</a>
719+
<ul class="sectlevel3">
720+
<li><a href="#_quoted_identifiers">Quoted Identifiers</a></li>
721+
<li><a href="#_keywords_as_identifiers">Keywords as Identifiers</a></li>
722+
<li><a href="#_names_containing_multiple_words">Names Containing Multiple Words</a></li>
723+
</ul>
724+
</li>
719725
<li><a href="#_numbers">4.3. Numbers</a></li>
720726
<li><a href="#_strings">4.4. Strings</a></li>
721727
<li><a href="#_filenames">4.5. Filenames</a></li>
@@ -834,6 +840,7 @@ <h1>The ALAN Adventure Language Reference Manual</h1>
834840
<li><a href="#_executive_summary">Executive Summary</a></li>
835841
</ul>
836842
</li>
843+
<li><a href="#_glossary">Glossary</a></li>
837844
</ul>
838845
</div>
839846
</div>
@@ -7864,6 +7871,8 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
78647871
<pre class="highlightjs highlight"><code data-lang="bnf" class="language-bnf hljs">identifier = letter {letter | digit | underscore}</code></pre>
78657872
</div>
78667873
</div>
7874+
<div class="sect3">
7875+
<h4 id="_quoted_identifiers"><a class="anchor" href="#_quoted_identifiers"></a>Quoted Identifiers</h4>
78677876
<div class="paragraph">
78687877
<p>There is also a second kind of identifier, namely the quoted identifier.</p>
78697878
</div>
@@ -7880,11 +7889,47 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
78807889
</div>
78817890
</div>
78827891
<div class="paragraph">
7883-
<p>A quoted identifier starts and ends with single quotes and may contain any character except quotes (including spaces).
7884-
By quoting any sequence of characters can become an identifier.
7885-
A quoted identifier may also be used to make an identifier out of a reserved word such as <code>Look</code>.
7886-
This is useful in the definition of the verb <code>look</code>.
7887-
It would look like:</p>
7892+
<p>A quoted identifier starts and ends with single quotes and may contain any character (including spaces) except single quotes&#8201;&#8212;&#8201;if you need to include a single quote inside a quoted identifier, you must <em>escape it</em> by doubling it, e.g.:</p>
7893+
</div>
7894+
<div class="listingblock">
7895+
<div class="content">
7896+
<pre class="highlightjs highlight"><code data-lang="alan" class="language-alan hljs">The <mark>'Bob''s House'</mark> IsA location. -- ID will be printed as "Bob's House"
7897+
End the.</code></pre>
7898+
</div>
7899+
</div>
7900+
<div class="paragraph">
7901+
<p>When the Alan compiler encounters two consecutive single quotes inside a quoted identifier, it will treat them as if they were one single quote which is part of the identifier, and not as a the single quote <em>delimiter</em> indicating the end of the identifier.</p>
7902+
</div>
7903+
<div class="paragraph">
7904+
<p>In the above example, the identifier will be printed as &#8220;Bob&#8217;s House&#8221; in the actual game&#8201;&#8212;&#8201;the enclosing single quote delimiters being ignored in print, and the two consecutive single quotes printed as one single quote.</p>
7905+
</div>
7906+
<div class="paragraph">
7907+
<p>Any sequence of characters enclosed within single quotes can become an identifier, except inside strings (where single quotes are treated as ordinary printable characters).</p>
7908+
</div>
7909+
<div class="admonitionblock note">
7910+
<table>
7911+
<tr>
7912+
<td class="icon">
7913+
<i class="fa icon-note" title="Note"></i>
7914+
</td>
7915+
<td class="content">
7916+
<div class="paragraph">
7917+
<p>A single-word identifier can be written within or without single quotes, indifferently (unless it&#8217;s a keyword).
7918+
Therefore, <code>'someID'</code> and <code>someID</code> both refer to the same identifier in the source code.</p>
7919+
</div>
7920+
</td>
7921+
</tr>
7922+
</table>
7923+
</div>
7924+
</div>
7925+
<div class="sect3">
7926+
<h4 id="_keywords_as_identifiers"><a class="anchor" href="#_keywords_as_identifiers"></a>Keywords as Identifiers</h4>
7927+
<div class="paragraph">
7928+
<p>Quoted identifiers may also be used to create an identifier out of a reserved word such as <code>Look</code>, <code>The</code>, etc.
7929+
This practice is known as <em><a href="#gloss_stropping">stropping</a></em>, and it allows the Alan compiler to distinguish between user-created identifiers and keywords in the source code, thus avoiding clashes that would lead to a compiler error.</p>
7930+
</div>
7931+
<div class="paragraph">
7932+
<p>This is useful (indeed, required), for example, in the definition of the verb &#8216;look&#8217;:</p>
78887933
</div>
78897934
<div class="listingblock">
78907935
<div class="content">
@@ -7894,6 +7939,48 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
78947939
End Verb 'look'.</code></pre>
78957940
</div>
78967941
</div>
7942+
<div class="admonitionblock important">
7943+
<table>
7944+
<tr>
7945+
<td class="icon">
7946+
<i class="fa icon-important" title="Important"></i>
7947+
</td>
7948+
<td class="content">
7949+
<div class="paragraph">
7950+
<p>Whenever an identifier contains an Alan keyword, it&#8217;s mandatory to use a quoted identifier.</p>
7951+
</div>
7952+
</td>
7953+
</tr>
7954+
</table>
7955+
</div>
7956+
<div class="paragraph">
7957+
<p>In the following example, the <code>'The Empty Room'</code> name needs to be enclosed within single quotes because it contains two Alan keywords (<code>The</code> and <code>Empty</code>), but there&#8217;s no need to do so with the <code>empty_room</code> identifier because the word <code>empty</code> doesn&#8217;t appear in isolated form (i.e. surrounded by spaces):</p>
7958+
</div>
7959+
<div class="listingblock">
7960+
<div class="content">
7961+
<pre class="highlightjs highlight"><code data-lang="alan" class="language-alan hljs">The empty_room IsA location --&gt; No need to stropp 'empty_room'.
7962+
NAME 'The Empty Room'. --&gt; Keywords 'THE' and 'EMPTY' stropped.
7963+
End The.</code></pre>
7964+
</div>
7965+
</div>
7966+
<div class="admonitionblock note">
7967+
<table>
7968+
<tr>
7969+
<td class="icon">
7970+
<i class="fa icon-note" title="Note"></i>
7971+
</td>
7972+
<td class="content">
7973+
<div class="paragraph">
7974+
<p>Stropping occurs only when the quoted identifier contains at least one Alan keyword.
7975+
Since in Alan it&#8217;s always permissible to enclose an identifier within single quotes (where <code>'someID'</code> and <code>someID</code> both refer to the same identifier), not every quoted identifier implies stropping, but stropping <em>always</em> requires a quoted identifier.</p>
7976+
</div>
7977+
</td>
7978+
</tr>
7979+
</table>
7980+
</div>
7981+
</div>
7982+
<div class="sect3">
7983+
<h4 id="_names_containing_multiple_words"><a class="anchor" href="#_names_containing_multiple_words"></a>Names Containing Multiple Words</h4>
78977984
<div class="paragraph">
78987985
<p>Quoted identifiers retain their exact content.
78997986
They may contain spaces and other special characters, which make them useful as long names for locations as in:</p>
@@ -7920,7 +8007,7 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
79208007
</div>
79218008
<div class="paragraph">
79228009
<p>The first word in the name will always be printed with a capital &#8216;E&#8217;.
7923-
However, when comparing the word to player input and other occurrences of the same word in the source, case will be ignored.
8010+
However, when comparing the word to player input and other occurrences of the same word in the source, letter casing will be ignored (i.e. comparison is case insensitive).
79248011
This means that you cannot have two words or identifiers that differ only in case, they will be the same and stored in the game data as one of the occurrences, which one is implementation dependent.</p>
79258012
</div>
79268013
<div class="admonitionblock warning">
@@ -7957,9 +8044,10 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
79578044
</div>
79588045
<div class="paragraph">
79598046
<p>Be careful when using quoted identifiers, especially if the player is supposed to use the word.
7960-
A player cannot input words containing spaces or other special characters or separators.
7961-
The only exception being underscores and dashes.
7962-
A player input word must start with a letter.</p>
8047+
A player cannot refer in the typed input to words which are defined in the code as single words containing spaces or other special characters or separators (the only exception being underscores and dashes).</p>
8048+
</div>
8049+
<div class="paragraph">
8050+
<p>Also, remember that a player input word must start with a letter; so the player won&#8217;t be able to refer to identifiers or names like &#8220;<code>1st</code>&#8221;, &#8220;<code>'70s</code>&#8221;, etc.</p>
79638051
</div>
79648052
<div class="admonitionblock tip">
79658053
<table>
@@ -7968,17 +8056,24 @@ <h3 id="_words_identifiers_and_names"><a class="anchor" href="#_words_identifier
79688056
<i class="fa icon-tip" title="Tip"></i>
79698057
</td>
79708058
<td class="content">
8059+
<div class="title">Escaping Single Quotes Inside Quoted Identifiers</div>
8060+
<div class="paragraph">
8061+
<p>
8062+
To include a single quote as part of a quoted identifier, double it (e.g. <code>'Tom''s Diner'</code>).
8063+
Inside the adventure, it will be printed as a single quote (&#8220;Tom&#8217;s Diner&#8221;).</p>
8064+
</div>
79718065
<div class="paragraph">
7972-
<p>To get a single quote within a quoted identifier repeat it (<code>'Tom''s Diner'</code>).</p>
8066+
<p>This technique is known as <em>escaping</em>, for it allows the Alan compiler to distinguish between the quote character as delimiters of the quoted identifier and its occurrence within the identifier as a printable character.</p>
79738067
</div>
79748068
</td>
79758069
</tr>
79768070
</table>
79778071
</div>
79788072
<div class="paragraph">
7979-
<p>Some of the identifiers in the source for an Alan game are by default used as player words.
8073+
<p>Some of the identifiers in the source of an Alan game are used by default as player words.
79808074
This is for example the case with verb names (unless a <code>Syntax</code> statement has been declared for the <code>Verb</code>) and object names (unless a <code>Name</code> clause has been used).
7981-
If these contain special characters, the player cannot enter them.</p>
8075+
If these contain special characters, the player won&#8217;t be able to refer to them in the typed input.</p>
8076+
</div>
79828077
</div>
79838078
</div>
79848079
<div class="sect2">
@@ -12767,6 +12862,27 @@ <h3 id="_executive_summary"><a class="anchor" href="#_executive_summary"></a>Exe
1276712862
</div>
1276812863
</div>
1276912864
</div>
12865+
<div class="sect1">
12866+
<h2 id="_glossary"><a class="anchor" href="#_glossary"></a>Glossary</h2>
12867+
<div class="sectionbody">
12868+
<div class="paragraph">
12869+
<p>Here follow some definitions of technical terms encountered in this manual, to bridge the gap between authorship as a writer and a programmer.
12870+
Although Alan is designed to be usable by non-programmers, knowing the terms of this glossary might help authors to better grasp some aspects of writing adventures in Alan, by providing an outlook into the wider context of computer languages and programming, and by providing the technical jargon required to discuss technical issues and further research some topics.</p>
12871+
</div>
12872+
<div class="dlist glossary">
12873+
<dl>
12874+
<dt><a id="gloss_stropping"></a>stropping</dt>
12875+
<dd>
12876+
<p>In the realm of computer programming, <em>stropping</em> is a technique to enable end users to create identifiers that contain reserved words of the language, by means of a special notation that allows the compiler (or interpreter) to distinguish between a user-defined identifier and a kewyord of the language, thus avoiding clashes that would prevent compilation/execution of the code.
12877+
In the Alan language, identifiers containing one or more reserved keywords can be stropped by enclosing the whole identifier within single straight quotes (<code>'</code>).
12878+
Example: <code>The 'The Empty Room' IsA location.</code> (keywords <code>THE</code> and <code>EMPTY</code> stropped).
12879+
For a detailed explanation and practical examples, see <a href="#_keywords_as_identifiers">Sect. 4.2.2</a>.
12880+
For more info on stropping, see <a href="https://en.wikipedia.org/wiki/Stropping_(syntax)" title="Visit Wikipedia page: 'Stropping (syntax)'" target="_blank" rel="noopener">Wikipedia</a>.</p>
12881+
</dd>
12882+
</dl>
12883+
</div>
12884+
</div>
12885+
</div>
1277012886
</div>
1277112887
<div id="footnotes">
1277212888
<hr>
@@ -12779,7 +12895,7 @@ <h3 id="_executive_summary"><a class="anchor" href="#_executive_summary"></a>Exe
1277912895
</div>
1278012896
<div id="footer">
1278112897
<div id="footer-text">
12782-
Version 0.1.92-PreReleaseBeta7<br>
12898+
Version 0.1.96-PreReleaseBeta7<br>
1278312899
</div>
1278412900
</div>
1278512901
<link rel="stylesheet" href="../_assets/hjs/styles/github.min.css">

manual/manual.pdf

31.9 KB
Binary file not shown.

0 commit comments

Comments
 (0)