From: Eric S. Raymond <esr@thyrsus.com>
Date: Fri, 7 Jul 2017 19:34:32 +0000 (-0400)
Subject: Comment cleanup.
X-Git-Tag: 2017-07-10~30
X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=100152c21df9a5508936e31a3971aea71a280165;p=open-adventure.git

Comment cleanup.
---

diff --git a/make_dungeon.py b/make_dungeon.py
index 3a78d4e..f8b3147 100755
--- a/make_dungeon.py
+++ b/make_dungeon.py
@@ -6,43 +6,7 @@
 #
 # The nontrivial part of this is the compilation of the YAML for
 # movement rules to the travel array that's actually used by
-# playermove().  This program first compiles the YAML to a form
-# identical to the data in section 3 of the old adventure.text file,
-# then a second stage unpacks that data into the travel array.
-#
-# Here are the rules of the intermediate form:
-#
-# Each row of data contains a location number (X), a second
-# location number (Y), and a list of motion numbers (see section 4).
-# each motion represents a verb which will go to Y if currently at X.
-# Y, in turn, is interpreted as follows.  Let M=Y/1000, N=Y mod 1000.
-#		If N<=300	it is the location to go to.
-#		If 300<N<=500	N-300 is used in a computed goto to
-#					a section of special code.
-#		If N>500	message N-500 from section 6 is printed,
-#					and he stays wherever he is.
-# Meanwhile, M specifies the conditions on the motion.
-#		If M=0		it's unconditional.
-#		If 0<M<100	it is done with M% probability.
-#		If M=100	unconditional, but forbidden to dwarves.
-#		If 100<M<=200	he must be carrying object M-100.
-#		If 200<M<=300	must be carrying or in same room as M-200.
-#		If 300<M<=400	game.prop(M % 100) must *not* be 0.
-#		If 400<M<=500	game.prop(M % 100) must *not* be 1.
-#		If 500<M<=600	game.prop(M % 100) must *not* be 2, etc.
-# If the condition (if any) is not met, then the next *different*
-# "destination" value is used (unless it fails to meet *its* conditions,
-# in which case the next is found, etc.).  Typically, the next dest will
-# be for one of the same verbs, so that its only use is as the alternate
-# destination for those verbs.  For instance:
-#		15	110022	29	31	34	35	23	43
-#		15	14	29
-# This says that, from loc 15, any of the verbs 29, 31, etc., will take
-# him to 22 if he's carrying object 10, and otherwise will go to 14.
-#		11	303008	49
-#		11	9	50
-# This says that, from 11, 49 takes him to 8 unless game.prop(3)=0, in which
-# case he goes to 9.  Verb 50 takes him to 9 regardless of game.prop(3).
+# playermove().
 
 import sys, yaml
 
@@ -604,6 +568,51 @@ def bigdump(arr):
     return out
 
 def buildtravel(locs, objs):
+    assert len(locs) <= 300
+    assert len(objs) <= 100
+    # THIS CODE IS WAAAY MORE COMPLEX THAN IT NEEDS TO BE.  It's the
+    # result of a massive refactoring exercise that concentrated all
+    # the old nastiness in one spot. It hasn't been finally simplified
+    # because there's no need to do it until one of the asserions
+    # fails. Hint: if you try cleaning this up, the acceptance test is
+    # simple - the output dungeon.c must not change.
+    #
+    # This function first compiles the YAML to a form identical to the
+    # data in section 3 of the old adventure.text file, then a second
+    # stage unpacks that data into the travel array.  Here are the
+    # rules of that intermediate form:
+    #
+    # Each row of data contains a location number (X), a second
+    # location number (Y), and a list of motion numbers (see section 4).
+    # each motion represents a verb which will go to Y if currently at X.
+    # Y, in turn, is interpreted as follows.  Let M=Y/1000, N=Y mod 1000.
+    #		If N<=300	it is the location to go to.
+    #		If 300<N<=500	N-300 is used in a computed goto to
+    #					a section of special code.
+    #		If N>500	message N-500 from section 6 is printed,
+    #					and he stays wherever he is.
+    # Meanwhile, M specifies the conditions on the motion.
+    #		If M=0		it's unconditional.
+    #		If 0<M<100	it is done with M% probability.
+    #		If M=100	unconditional, but forbidden to dwarves.
+    #		If 100<M<=200	he must be carrying object M-100.
+    #		If 200<M<=300	must be carrying or in same room as M-200.
+    #		If 300<M<=400	game.prop(M % 100) must *not* be 0.
+    #		If 400<M<=500	game.prop(M % 100) must *not* be 1.
+    #		If 500<M<=600	game.prop(M % 100) must *not* be 2, etc.
+    # If the condition (if any) is not met, then the next *different*
+    # "destination" value is used (unless it fails to meet *its* conditions,
+    # in which case the next is found, etc.).  Typically, the next dest will
+    # be for one of the same verbs, so that its only use is as the alternate
+    # destination for those verbs.  For instance:
+    #		15	110022	29	31	34	35	23	43
+    #		15	14	29
+    # This says that, from loc 15, any of the verbs 29, 31, etc., will take
+    # him to 22 if he's carrying object 10, and otherwise will go to 14.
+    #		11	303008	49
+    #		11	9	50
+    # This says that, from 11, 49 takes him to 8 unless game.prop(3)=0, in which
+    # case he goes to 9.  Verb 50 takes him to 9 regardless of game.prop(3).
     ltravel = []
     verbmap = {}
     for i, motion in enumerate(db["motions"]):
@@ -685,28 +694,8 @@ def buildtravel(locs, objs):
 
     # At this point the ltravel data is in the Section 3
     # representation from the FORTRAN version.  Next we perform the
-    # same mapping into the runtime format.  This was the C translation
-    # of the FORTRAN code:
-    # long loc;
-    # while ((loc = GETNUM(database)) != -1) {
-    #     long newloc = GETNUM(NULL);
-    #     long L;
-    #     if (TKEY[loc] == 0) {
-    #         TKEY[loc] = TRVS;
-    #     } else {
-    #         TRAVEL[TRVS - 1] = -TRAVEL[TRVS - 1];
-    #     }
-    #     while ((L = GETNUM(NULL)) != 0) {
-    #         TRAVEL[TRVS] = newloc * 1000 + L;
-    #         TRVS = TRVS + 1;
-    #         if (TRVS == TRVSIZ)
-    #             BUG(TOO_MANY_TRAVEL_OPTIONS);
-    #     }
-    #     TRAVEL[TRVS - 1] = -TRAVEL[TRVS - 1];
-    # }
-    #
-    # In order to de-crypticize the runtime code, we're going to break these
-    # magic numbers up into a struct.
+    # same mapping into wgat used to be the runtime format.
+
     travel = [[0, "LOC_NOWHERE", 0, 0, 0, 0, 0, 0, "false", "false"]]
     tkey = [0]
     oldloc = 0