From: Eric S. Raymond <esr@thyrsus.com>
Date: Mon, 1 Nov 2004 22:36:16 +0000 (+0000)
Subject: Better project documentation.
X-Git-Tag: 2.0~441
X-Git-Url: https://jxself.org/git/?p=super-star-trek.git;a=commitdiff_plain;h=d5826a672dd4afc591476655b4905cb6542cd89c

Better project documentation.
---

diff --git a/TODO b/TODO
index 505b952..8062cb1 100644
--- a/TODO
+++ b/TODO
@@ -18,7 +18,7 @@
   non-"super" version Matuszek and Reynolds wrote.)
 
   Dave Matuszek tells me that SRSCAN, MOVE, PHASERS, CALL, STATUS,
-  IMPULSE, PHOTONS, ABANDON, LRSCAN, WARP, SHIELDS, DESTRUCT\n" CHART,
+  IMPULSE, PHOTONS, ABANDON, LRSCAN, WARP, SHIELDS, DESTRUCT CHART,
   REST, DOCK, QUIT, and DAMAGE were in the original non-"super" version.
 
 * Write a curses-based interface.  Shouldn't be hard, all output goes through
diff --git a/makefile b/makefile
index 5ca423b..b459f7e 100644
--- a/makefile
+++ b/makefile
@@ -14,7 +14,7 @@ sst:  $(OFILES)
 
 $(OFILES):  $(HFILES)
 
-sst-doc.txt:
+sst-doc.txt: sst-doc.xml
 	xmlto --skip-validation txt sst-doc.xml
 sst.doc: sst-doc.txt
 	makehelp.py >sst.doc
diff --git a/sst-doc.xml b/sst-doc.xml
index c5863a7..392628a 100644
--- a/sst-doc.xml
+++ b/sst-doc.xml
@@ -1652,22 +1652,32 @@ site</ulink>.</para>
 </para></listitem>
 </itemizedlist>
 
-<para>Modifications I made:</para>
+<para>Modifications I've made:</para>
 
 <itemizedlist>
 <listitem><para>
-I converted the flat-text SST.DOC file to XML-Docbook so it could be webbed.
-(That's what you're reading now.)
+I converted the flat-text SST.DOC file to XML-Docbook so it can be
+webbed. (That's what you're reading now.)
+</para></listitem>
+<listitem><para>
+The command-help code needed a rewrite because the flat-text form of
+the documentation is now generated from XML and doesn't have the
+easily recognizable section delimiters it used to.  I wrote a script
+to filter that flat-text form into an sst.doc that's easy to parse for
+command descriptions, and changed some logic in sst.c to match.
 </para></listitem>
 <listitem><para>
-I cleaned up a lot of grubby FORTRANisms in the code internals.
+I've cleaned up a lot of grubby FORTRANisms in the code internals --
+used sizeof(), replaced magic numeric constants with #defines,
+that sort of thing.
 </para></listitem>
 <listitem><para>
 I fixed a surprising number of typos in the code and documentation.
 </para></listitem>
 <listitem><para>
-I changed the freeze logic to emit an identifiable magic number and 
-the thaw logic to check for it.
+All the game state now lives in one big structure that can be
+written to and read from disk as one blob.  The write gives it an
+an identifiable magic number and the thaw logic checks for same. 
 </para></listitem>
 </itemizedlist>