Comments Updates

Remove obsolete comments and add new ones annotating TODOs, etc.

manual/manual_05.adoc

@@ -73,11 +73,6 @@ The exact list of these words, for every language natively supported in Alan, is
 
 The following built-in syntax variations are available to the player:
 
-// @NOTE: I've styled in ALL-CAPS the player-words in the examples, to highlight
-//        them. It makes sense, because often there are multiple player-words in
-//        in an input command, and we want the reader to focus only on the ones
-//        being exemplified.
-
 * Concatenation of commands via (((AND (player input)))) (((THEN (player input)))) *AND*-words, like:
 +
 [example,role="gametranscript"]
@@ -212,7 +207,7 @@ This makes it possible to use natural words as nouns and create "`{nbsp}l`'{nbsp
 
 // @NOTE: Instead of "adventure DESCRIPTION (source)" we could use:
 //        "adventure GRAMMAR (source)"? or "DEFINITION"?
-//        In any case, in this particulare sentence using DESCRIPTION and DESCRIBED
+//        In any case, in this particular sentence using DESCRIPTION and DESCRIBED
 //        so close to each other doesn't sound good. But I like GRAMMAR because
 //        the term is used in BNF contexts, so it might be adopted in the Manual
 //        (not just here, but elsewhere too).
@@ -251,7 +246,11 @@ So, the execution of various parts of the adventure source can also be said to h
 * *A rule* -- rules are executed after each actor (including the hero) and after each event, with the focus set to the complete game world.
 
 
-
+// @NOTE: "Moving Actors" is an ambiguous title -- does it mean "actors that are moving"
+//        or "how to move around actors?". Possibly "Actors Movement" would be better.
+// BEWARE that before changing the title we need to search through all sources for
+// possible XRefs that also need to be changed accordingly (since we're still using
+// the actual title as the XRef)!
 
 == Moving Actors
 
@@ -295,11 +294,8 @@ It must consist of the single word `undo`.
 //        this section with the wider world of Interactive Fiction, games distribution
 //        common practices, etc.
 
-// @TODO: File extensions of transcripts and solution files? Arun seems to use
-//        ".log" as default extension. Might be worth mentioning that file extensions
-//        are not important here, and that usually the convention is to use ".sol"
-//        for solution files, and the various extensions used for transcripts (by
-//        other terps as well!).
+// @TODO: ALAN now adopts the new official '.a3s' and '.a3t' extensions, so we
+//        should mention them here!
 
 Most versions of the Alan interpreter, Arun, supports both the creation of a transcript for the game in progress, as well as playing back a saved transcript as input passed to the interpreter.