Documentation polishing.

[open-adventure.git] / advent.adoc

diff --git a/advent.adoc b/advent.adoc
index d0fd29b09918b1c54f4af0dcdfe3a0bbc6a57970..6257e6c1b4f5e8926fb26101c8bc9310765d3d49 100644 (file)
--- a/advent.adoc
+++ b/advent.adoc
@@ -5,10 +5,10 @@
 advent - Colossal Cave Adventure
 
 == SYNOPSIS ==
 advent - Colossal Cave Adventure
 
 == SYNOPSIS ==

-*advent* [-l logfile] [-o]
+*advent* [-l logfile] [-o] [-r savefile] [script...]

 
 == DESCRIPTION ==
 
 == DESCRIPTION ==

-The original Colossal Cave Adventure from 1976-77 was the origin of all
+The original Colossal Cave Adventure from 1976-1977 was the origin of all

 later text adventures, dungeon-crawl (computer) games, and computer-hosted
 roleplaying games.
 
 later text adventures, dungeon-crawl (computer) games, and computer-hosted
 roleplaying games.
 


@@ -18,16 +18,21 @@ adventure".  To learn more about the changes since the 350-point
 original, type 'news' at the command prompt.
 
 There is an 'adventure' in the BSD games package that is a C port by
 original, type 'news' at the command prompt.
 
 There is an 'adventure' in the BSD games package that is a C port by

-Jim Gillogly of the 1976 ancestor of this game.  To avoid a name
+Jim Gillogly of the Don Woods's 1977 version of this game.  To avoid a name

 collision, this game builds as 'advent', reflecting the fact that the
 collision, this game builds as 'advent', reflecting the fact that the

-PDP-10 on which it originally ran limited filenames to 6 characters.
+PDP-10 on which the game originally ran limited filenames to 6 characters.

 
 This version is released as open source with the permission and
 encouragement of the original authors.
 
 
 This version is released as open source with the permission and
 encouragement of the original authors.
 

-Unlike the original, this version supports use of your arrow keys to edit
-your command line in place.  Basic Emacs keystrokes are supported, and
-your up/down arrows access a command history.
+Unlike the original, this version has a command prompt and supports
+use of your arrow keys to edit your command line in place.  Basic
+Emacs keystrokes are supported, and your up/down arrows access a
+command history.
+
+Some minor bugs and message typos have been fixed.  Otherwise, the
+"version" command is almost the only way to tell you're not running
+Don's 1977 version.

 
 To exit the game, type Ctrl-D (EOF).
 
 
 To exit the game, type Ctrl-D (EOF).
 


@@ -37,16 +42,42 @@ There have been no gameplay changes.
 
 -l:: Log commands to specified file.
 
 
 -l:: Log commands to specified file.
 

--s:: Suppress Emacs-like line editing and command history.
-

 -r:: Restore game from specified file
 
 -r:: Restore game from specified file
 

--o:: Old-style.  Restores original interface, no prompt or line editing.
+-a:: Load from specified file and autosave to it on exit or signal.
+
+-o:: Old-style.  Reverts some minor cosmetic fixes in game
+     messages. Restores original interface, no prompt or line editing.
+     Also ignores new-school one-letter commands l, x, g, z, i. Also
+     case-smashes and truncates unrecognized text when echoed.
+
+Normally, game input is taken from standard input.  If script file
+arguments are given, input is taken from them instead.  A script file
+argument of '-' is taken as a directive to read from standard input.

 
 == BUGS ==
 
 The binary save file format is fragile, dependent on your machine word
 
 == BUGS ==
 
 The binary save file format is fragile, dependent on your machine word

-size and endianness, and unlikely to survive through version bumps.
+size and endianness, and unlikely to survive through version bumps. There
+is a version check.
+
+The input parser was the first attempt *ever* at natural-language
+parsing in a game and has some known deficiencies.  While later text
+adventures distinguished between transitive and intransitive verbs,
+Adventure's grammar distinguishes only between motion and action
+verbs. Motions are always immediate in their behavior, so both ACTION
+MOTION and MOTION ACTION (and even MOTION NOUN and MOTION MOTION) are
+invariably equivalent to MOTION (thus GO NORTH means NORTH and JUMP
+DOWN means JUMP). Whereas, with actions and nouns, the parser collects
+words until it's seen one of each, and then dispatches; if it reaches
+the end of the command without seeing a noun, it'll dispatch an
+"intransitive" action. This makes ACTION1 ACTION2 equivalent to
+ACTION2 (thus TAKE INVENTORY means INVENTORY), and NOUN ACTION
+equivalent to ACTION NOUN.
+
+Thus you get anomalies like "eat building" interpreted as a command
+to move to the building. These should not be reported as bugs; instead,
+consider them historical curiosities.

 
 == REPORTING BUGS ==
 Report bugs to Eric S. Raymond <esr@thyrsus.com>.  The project page is
 
 == REPORTING BUGS ==
 Report bugs to Eric S. Raymond <esr@thyrsus.com>.  The project page is