From 1b167e5e72e0b4ea4b991293abaf9b8ff1eac599 Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Mon, 12 Jun 2017 22:02:32 -0400 Subject: [PATCH] New notes.adoc file; major documentation update. --- Makefile | 4 +- README.adoc | 12 ++++- history.adoc | 45 ------------------- notes.adoc | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 137 insertions(+), 49 deletions(-) create mode 100644 notes.adoc diff --git a/Makefile b/Makefile index b0e1adf..f9cbb85 100644 --- a/Makefile +++ b/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 diff --git a/README.adoc b/README.adoc index b513dc4..e511d88 100644 --- a/README.adoc +++ b/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 + + diff --git a/history.adoc b/history.adoc index 8a0f8bf..43bc350 100644 --- a/history.adoc +++ b/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] diff --git a/notes.adoc b/notes.adoc new file mode 100644 index 0000000..1c06c80 --- /dev/null +++ b/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 -- 2.31.1