New notes.adoc file; major documentation update.

Makefile

@@ -80,7 +80,7 @@ check: advent
 html: advent.html history.html hints.html
 
 # README.adoc exists because that filename is magic on GitLab.
-DOCS=COPYING NEWS README.adoc TODO advent.adoc history.adoc hints.adoc advent.6
+DOCS=COPYING NEWS README.adoc TODO advent.adoc history.adoc notes.adoc hints.adoc advent.6
 TESTFILES=tests/*.log tests/*.chk tests/README tests/decheck tests/Makefile
 
 # Can't use GNU tar's --transform, needs to build under Alpine Linux.
@@ -91,7 +91,7 @@ advent-$(VERS).tar.gz: $(SOURCES) $(DOCS)
 	(tar -T MANIFEST -czvf advent-$(VERS).tar.gz)
 	@(rm advent-$(VERS))
 
-release: advent-$(VERS).tar.gz advent.html history.html hints.html
+release: advent-$(VERS).tar.gz advent.html history.html hints.html notes.html
 	shipper version=$(VERS) | sh -e -x
 
 refresh: advent.html

README.adoc

@@ -6,7 +6,8 @@ development written by the original authors.  The authors have given
 permission and encouragement for this release.
 
 The file history.adoc contains a more detailed history of this game
-and its ancestors.
+and its ancestors.  The file notes.adoc is the maintainer's notes,
+describing project goals and recent changes.
 
 This project is called "Open Adventure" because it's not at all clear
 how to number Adventure past 2.5 without misleading or causing
@@ -15,5 +16,12 @@ original 6-character name on the PDP-10 has been reverted to for the
 executable in order to avoid a collision with the BSD games port of
 the ancestral 1977 version.
 
-You can run a regression test on the code with 'make check'.
+You can run a regression test on the code with 'make check'. Extreme
+care has been taken to not silently change gameplay. By policy, all
+user-visible changes from 2.5 are revertible with the -o (oldstyle)
+option.
+
+// end
+
+
 

history.adoc

@@ -135,51 +135,6 @@ museumization after historians rediscovered Yob's game.)
 Neither of these games used an attempt at a natural-language parser
 even as primitive as Adventure's.
 
-== Nomenclature ==
-
-This project is called "Open Adventure" because it's not at all clear
-to number Adventure past 2.5 without misleading or causing
-collisions. Various of the non-mainline versions have claimed to be
-versions 3, 4, 5, 6, 7 and for all I know higher than that.  It seems
-best just to start a new numbering series while acknowledging the
-links back.
-
-We have reverted to "advent" for the binary to avoid a name collision
-with the BSD Games version.
-
-== Functional changes in Open Adventure ==
-
-By default, advent issues "> " as a command prompt.  This feature
-became common in many variants after the original 350-point version,
-but was never backported into Crowther & Woods's main line before now.
-The "-o" (oldstyle) version reverts the behavior.
-
-A "seed" command has been added.  This is not intended for human use
-but as a way for game logs to set the PRNG (pseudorandom-number generator) so
-that random events (dwarf & pirate appearances, the bird's magic word)
-will be reproducible.
-
-A -l command-line option has been added. When this is given (with a
-file path argument) each command entered will be logged to the
-specified file.  Additionally, a generated "seed" command will be put
-early in the file capturing the randomized start state of the PRNG
-so that replays of the log will be reproducible.
-
-Using "seed" and -l, the distribution now includes a regression-test
-suite for the game.  Any log captured with -l (and thus containing
-a "seed" command) will replay reliably, including random events.
-
-The adventure.text file is no longer required at runtime.  Instead, it
-is compiled at build time to a source module containing C structures,
-which is then linked to the advent binary.
-
-The game-save format has changed.  This was done to simplify
-FORTRAN-derived code that formerly implemented these functions;
-without C's fread(3)/fwrite() and structs it was necessarily pretty
-ugly by modern stabdards. Encryption and checksumming have been
-discarded - it's pointless to try tamper-prooing saves when everyone
-has the source code.
-
 == Sources ==
 
 [bibliography]

notes.adoc

@@ -0,0 +1,125 @@
+= Open Adventure Maintainer's Notes =
+by Eric S. Raymond
+
+In which we explain what has been done to this code since Don Woods
+authorized us to ship it under an open-source license.  There's a
+separate link:history.html[history] describing how it came to us.
+
+== Who we are ==
+
+The principal maintainers of this code are Eric S. Raymond and Jason
+Ninneman.  Eric received Don Woods's encouragement to update and ship
+the game; Jason signed on early in the process to help.
+
+== Nomenclature ==
+
+This project is called "Open Adventure" because it's not at all clear
+to number Adventure past 2.5 without misleading or causing
+collisions. Various of the non-mainline versions have claimed to be
+versions 3, 4, 5, 6, 7 and for all I know higher than that.  It seems
+best just to start a new numbering series while acknowledging the
+links back.
+
+We have reverted to "advent" for the binary to avoid a name collision
+with the BSD Games version.
+
+== Philosophy ==
+
+Extreme care has been taken not to make changes that would alter the
+logic of the game as we received it from Don Woods.  By policy, all
+user-visible changes must be revertible with the -o (oldstyle) option.
+
+It is a goal of this project to exactly preserve the *behavior* of
+430-point Adventure, but the implementation of it is fair game for
+improvement. In particular, we are concerned to move it to a form that
+is (a) readable, and (b) friendly to forward translation to future
+languages.  It has already survived a move from FORTRAN to C; a future
+as a Python or Go translation seems possible, even probable.
+
+== Functional changes ==
+
+By default, advent issues "> " as a command prompt.  This feature
+became common in many variants after the original 350-point version,
+but was never backported into Crowther & Woods's main line before now.
+The "-o" (oldstyle) version reverts the behavior.
+
+A "seed" command has been added.  This is not intended for human use
+but as a way for game logs to set the PRNG (pseudorandom-number generator) so
+that random events (dwarf & pirate appearances, the bird's magic word)
+will be reproducible.
+
+A -l command-line option has been added. When this is given (with a
+file path argument) each command entered will be logged to the
+specified file.  Additionally, a generated "seed" command will be put
+early in the file capturing the randomized start state of the PRNG
+so that replays of the log will be reproducible.
+
+Using "seed" and -l, the distribution now includes a regression-test
+suite for the game.  Any log captured with -l (and thus containing
+a "seed" command) will replay reliably, including random events.
+
+The adventure.text file is no longer required at runtime.  Instead, it
+is compiled at build time to a source module containing C structures,
+which is then linked to the advent binary.
+
+The game-save format has changed.  This was done to simplify
+FORTRAN-derived code that formerly implemented these functions;
+without C's fread(3)/fwrite() and structs it was necessarily pretty
+ugly by modern standards. Encryption and checksumming have been
+discarded - it's pointless to try tamper-proofing saves when everyone
+has the source code.
+
+== Translation ==
+
+The 2.5 code was a mechanical C translation of a FORTRAN original.
+There were gotos everywhere and the code was, though functional,
+ugly and quite unreadable.
+
+Jason Ninneman and I have moved it to what is almost, but not quite,
+idiomatic modern C.  We refactored the right way, checking correctness
+against a comprehesive test suite that we built first and verified with
+coverage tools. This is what you are running when you do "make check".
+
+This move entailed some structural changes.  The most important was
+the refactoring of 354 gotos into if/loop/break structures.  We
+also abolished almost all shared globals; the main one left is a
+struct holding the game's saveable/restorable state.
+
+The original code was greatly complicated by a kind of bit-packing
+that was performed because the FORTRAN it was written in had no string
+type.  Text from the adventure.text file was compiled into sequences
+of sixbit code points in a restricted character set, packed 5 to a
+32-bit word (it seems clear from the code that words were originally
+*6* chars each packed into a PDP-10 36-bit word).  A command noun or
+verb was one of these words, and what would be string operations in a
+more recent language were all done on sequences of these words.
+
+We are still in the process of removing all this bit-packing cruft
+in favor of proper C strings.  C strings may be a weak and leaky
+abstraction, but this is one of the rare cases in which they are
+an obvious improvement over what they're displacing... 
+
+The code falls a short of being fully modern C in the following
+ways:
+
+* We have not attempted to translate the old code to pointer-based
+  idioms (as opposed, in particular, to integer-based array indexing).
+  We don't need whatever minor performance gains this might collect,
+  and the choice to refrain will make forward translation into future
+  languages easier.
+
+* There are 20 gotos left that resist restructuring; all but one of
+  these are in the principal command interpreter function implementing
+  its state machine.  A 21st, a two-level loop breakout, is not reducible
+  even in principle.
+
+* Linked lists (for objects at a location) are implemented using an array
+  of link indices. This is a surviving FORTRANism that is quite unlike
+  normal practice in C or any more modern language.  We have not tried
+  to fix it because doing so would (a) be quite difficult, and (b)
+  compromise forward-portability to other languages.
+
+* The code still has an unfortunately high density of magic numbers - in
+  particular, numeric object and room IDs.
+
+// end