//	A-code source comments for the Annotated Adventure

var c00 = 'COMMENT TO BE SUPPLIED.';
var c01 = 'The uppercasing of A-code directives and names is purely conventional. Except for the text of messages and descriptions, A-code is completely case insensitive. The layout used in this example is also purely conventional.';
var c02 = 'All leading spaces are equivalent to a single space. The forward slash is used to denote the real beginning of a text line, if this needs to start with spaces.';
var c03 = 'A paragraph of text is equivalent to a single line of text -- A-code does its own dynamic filling and justifying of lines, in order to accommodate the text switch facility.';
var c04 = 'Symbolic text names assist the readability of the code, but are not available to the player as a part of the vocabulary. The same does not (necessarily) apply to place or object names.';
var c05 = 'This text contains a text switch, which allows the text to change depending on the value of the qualifying object, place, variable or constant.';
var c06 = 'By default, place names are not added to the vocabulary, but they can be forced into the vocabulary by being prefixed with the plus sign. In this case we are intending to enable the player to say GO HALL.';
var c07 = 'Places have up to two descriptions, the % sign marking the start of the long one. By default, the skeleton will show the long description only the first time the player enters a location, or when the LOOK command is used with no arguments. This behaviour is altered by the commands TERSE, BRIEF and VERBOSE.';
var c08 = 'By default, object name and synonyms are added to the vocabulary. The equals sign tells A-code that the synonym so tagged is to be equated to the last preceding synonym without the tag. Hence if the user mentions BRASS HOOK and the A-code needs to echo the nominated object, HOOK will be echoed even though it was BRASS that got parsed, and HOOK ignored.';
var c09 = 'Objects have up to three distinct descriptions. The first is the inventory description, missing in the case of the hook, because it is not an object the player can pick up. The second, denoted by the % sign, is the "here you can see" one.  The third, denoted by the & sign is the description displayed when the object is being examined.';
var c10 = 'The !` at the beginning of a line is one way to denote a text without the terminating line feed. In this case the skeleton may need to add <b>(worn)</b> to the inventory description. A text switch could be used instead, but that would be a bit more complicated given that the skeleton uses flags rather than states to signal objects being worn.';
var c11 = 'It is perfectly sensible to have objects with no descriptions at all. Typically, they get described as a part of a location description, or by explicit messages in response to player commands.';
var c12 = 'Lines with an asterisk in the first position are comments. In-line comments are also allowed (though not within text/description bodies) and are enclosed in curly braces (these mean something else altogether within texts!).';
var c13 = 'All other verbs we need are already pre-defined by the skeleton.';
var c14 = 'The HUNG state will be shared by the cloak and the hook. The value only has to be specified because we have no need to name the default (zero) state as well.';
var c15 = 'The AT directive associates a chunk of code with the named location. This code is executed by the skeleton automatically whenever the player is at the location. Any number of chunks of code can be associated with a location. They will be executed in the order of their definition.';
var c16 = 'This says: if the player mentioned NORTH, OUT or HALL, go to the hall.';
var c17 = 'All objects, places and variables have easily modifiable sets of binary flags pre-defined by the skeleton. This statement checks whether the current location is illuminated. The value of HERE is maintained automatically, though in this case BIT BAR, LIT would have worked just as well.';
var c18 = 'Compound logicals in A-code are unusual in following prefix logic. This makes them mostly intuitive, except to professional programmers! Specifically, conditions are evaluated in order of their appearance. E.g. conceptually "A or B and C or D" is equivalent to "((A or B) and C) or D".';
var c19 = 'The text of THE.OUTCOME has an embedded switch to say you have lost/won. The text is qualified by the current state of MESSAGE, which will have the appropriate value (zero or less for lost, above zero for won).';
var c20 = 'The state of MESSAGE is initialised to 3 and decremented every time the player does anything in the bar if the light is not on.';
var c21 = 'The QUIP directive produces the message and aborts all further processing of the current player input.';
var c22 = 'This evaluates to true only if the player used both HANG and CLOAK. For historical reasons, the code following a KEYWORD directive is terminated not by FIN, but by the start of the next chunk of code.';
var c23 = 'Just being pernickety here. We could allow the player to hang the cloak without explicitly removing it first. We would have to remember to clear its WORN flag, of course.';
var c24 = 'That is: move the cloak from player inventory to the current location.';
var c25 = 'Set the "illuminated" flag for the bar.';
var c26 = 'The BEEN.HERE flag is automatically set for a location when it is first visited and is used in the default description mode to decide whether a full location description is to be shown. By clearing the bit, we ensure that the player will be given the full description now that the bar is lit.';
var c27 = 'Like the KEYWORD directive, ANYOF does not take a FIN to terminate the conditional code. It evaluates to true if the player mentioned any of the listed words.';
var c28 = 'Generally action HANG simply fails. The code specific to the cloakroom is handled by the AT CLOAKROOM directive. This is merely a question of style -- it could be just as well handled here, by using the IFAT CLOAKROOM test, instead of using KEYWORD HANG, CLOAK in the AT CLOAKROOM code.';
var c29 = 'No need to handle the case of not being near the cloak (i.e. holding it or the cloak being at this location). No need to handle the HANG command with no object either. All of this will be done by the skeleton code automatically if the command is not handled explicitly.';
var c30 = 'The INIT code chunks are executed once only, when the game is started. They are executed in order of their definition. The <b>clcode.acd</b> file is being inserted between the skeleton INIT and REPEAT sections, so this initialisation code will be the last to execute -- overriding any default initialisation done by the skeleton.';
var c31 = 'Tell skeleton that the MESSAGE object has no description separate from the location, to avoid throwing a blank line before its non-existent description.';
var c32 = 'Define the cloak to the skeleton as something that can be picked up.';
var c33 = 'Define the cloak to the skeleton as something that can be worn.';
var c34 = 'Note that the cloak is actually worn.';
var c35 = 'This is where the player starts.';
var c36 = 'This is the first declared repeat segment, so it will get executed ahead of the queue in the main loop. The purpose is to pick up the cloak if we have just dropped it -- this is just to keep all extra code together in a separate file; the alternative would have been to edit <b>skaction.acd</b> and intercept the dropping of the cloak there.';