More port fixes for the Python version.
[super-star-trek.git] / doc / sst-doc.xml
index ec0a208389d66a8dfb4f374cd2072a51a3eac8cd..ecb52aac0938496331d9ba5d19b6d4eb8b747d5b 100644 (file)
 </authorgroup>
 
 <legalnotice>
-<para>Permission is hereby granted for the copying, distribution,
-modification and use of this program and associated documentation
-for recreational purposes, provided that all references to the
-authors are retained.  However, permission is not and will not be
-granted for the sale or promotional use of this program or program
-documentation, or for use in any situation in which profit may be
-considered an objective, since it is the desire of the authors to
-respect the copyrights of the originators of Star Trek.</para>
+<para>Super Star Trek 2K is issued under the BSD license.  Nothing in
+this license grants or purports to grant any rights with respect to
+the trademarks, copyrights or other property of the originators of
+Star Trek or their successors in interest.  We recognize and support
+their right under the Berne Convention to recover damages for any uses
+of this program which compromise their legitimate interest in
+protecting their copyrights and trademarks or unjustly enrich
+others.</para>
 </legalnotice>
 </bookinfo>
 
@@ -253,13 +253,14 @@ The Emeritus game is strictly for masochists.</para>
 
 <para>The fourth question, new in SST2K, sets your game options.  A
 blank answer or 'fancy' enables all SST2K features.  The option
-'plain' disables a number of features (Tholians, planets &amp;
-dilithium, Thingies shooting back, deep-space-probes, Klingon ramming
-and movement, time-warping through black holes, death-ray upgrade),
-approximating the original CDC 6600 FORTRAN game from UT Austin.  The
-option 'almy' approximates Tom Almy's C translation from 1979,
-disabling Thingies shooting back, base shields, and time-warping
-through black holes.</para>
+'plain' approximated the original CDC 6600 FORTRAN game from UT Austin
+and disables a number of features: Tholians, planets &amp; dilithium,
+Thingies shooting back, deep-space-probes, Klingon ramming and
+movement, time-warping through black holes, death-ray
+upgrade. inhabited worlds.  The option 'almy' approximates Tom Almy's
+C translation from 1979, disabling Thingies shooting back, base
+shields, time-warping through black holes, and inhabited
+worlds.</para>
 
 </chapter>
 <chapter><title>How To Issue Commands</title>
@@ -340,7 +341,7 @@ complicated, but you will learn the abbreviations quickly enough.</para>
 </orderedlist>
 
 <para>If you are part way through entering a command and you change your
-minde, you can cancel the command by typing -1 as one of the
+mind, you can cancel the command by typing -1 as one of the
 parameters, with the exception of the manual move command.</para>
 
 <para>If anything is not clear to you, experiment.  The worst you can do is
@@ -387,7 +388,8 @@ described by an example.</para>
 There are ordinary Klingons (K) at sectors 5 - 8 and 6 - 2, and a
 Klingon Commander (C) at 9 - 9.  The (GULP)
 <quote>Super-commander</quote> (S) is occupies sector 4 - 4, and a
-Romulan (R) is at 1 - 6.  A planet (P) is at sector 7 - 6.  There are
+Romulan (R) is at 1 - 6.  An uninhabited planet (P) is at sector 7 - 6
+(if it were inhabited, it would display as a '@').  There are
 also a large number of stars (*). The periods (.) are just empty
 space&mdash;they are printed to help you get your bearings.  Sector 6
 - 4 contains a black hole ( ).</para>
@@ -407,7 +409,23 @@ short-range scan anytime you like.</para>
 
 <para>If your short-range sensors are damaged, this command will only show
 the contents of adjacent sectors.</para>
+
+</sect1>
+<!--
+<sect1><title>Visual Scan</title>
+
+<literallayout>
+Mnemonic:  VISUAL
+Shortest abbreviation: V
+</literallayout>
+
+<para>A visual scan is made in a particular direction of three sectors
+in the general direction specified.  This takes time, and Klingons can
+attack you, so it should be done only when short-range sensors are
+out.</para>
+
 </sect1>
+-->
 <sect1><title>Status Report</title>
 
 <literallayout>
@@ -596,6 +614,7 @@ galaxy, which you are not permitted to cross.</para>
 
 <para>Long-range scans are free.  They use up no energy or time, and can be
 done safely regardless of battle conditions.</para>
+
 </sect1>
 <sect1><title>Star Chart</title>
 
@@ -714,8 +733,9 @@ the current quadrant, the shortest command would be</para>
 <para>and it will be done.  In automatic mode, either two or four numbers
 must be supplied.</para>
 
-<para>Automatic mode utilizes the ship's <quote>battle computer.</quote>  If the
-computer is damaged, manual movement must be used.</para>
+<para>Automatic mode utilizes the ship's <quote>battle
+computer.</quote> If the computer is damaged, manual movement must be
+used.</para>
 
 <para>If warp engines are damaged less than 10 stardates (undocked) you can
 still go warp 4.</para>
@@ -1097,7 +1117,8 @@ Mnemonic:  DESTRUCT
 
 <para>You may self-destruct, thus killing yourself and ending the game.  If
 there are nearby Klingons, you may take a few of them with you (the
-more energy you have left, the bigger the bang).</para>
+more energy you have left, the bigger the bang). It is possible to
+win this way, if you kill off your last adversaries with the blast.</para>
 
 <para>In order to self-destruct you must remember the password you typed in
 at the beginning of the game.</para>
@@ -1435,6 +1456,11 @@ inform you how long the base under attack can last.  Since the
 <quote>Super-Commander</quote> is more powerful than an ordinary
 commander, he can destroy a base more quickly.</para>
 
+<para>Inhabited worlds can be attacked, enslaved, and forced to 
+build more Klingon starships.  They will send out a distress call
+by subspace radio when they are attacked, and you will lose contact
+with them when they are enslaved.</para>
+
 <para>The <quote>Super-Commander</quote> travels around the galaxy at
 a speed of about warp 6 or 7.  His movement is strictly time based;
 the more time passes, the further he can go.</para>
@@ -1502,11 +1528,12 @@ the game, your kill rate is based on a minimum of 5 stardates.</para>
 <para>You lose&mdash;</para>
 
 <orderedlist>
+<listitem><para>300 points for each inhabited world you destroy,</para></listitem>
 <listitem><para>200 points if you get yourself killed,</para></listitem>
 <listitem><para>100 points for each starbase you destroy,</para></listitem>
 <listitem><para>100 points for each starship you lose,</para></listitem>
 <listitem><para>45 points for each time you had to call for help,</para></listitem>
-<listitem><para>10 points for each planet you destroyed,</para></listitem>
+<listitem><para>10 points for each uninhabited planet you destroyed,</para></listitem>
 <listitem><para>5 points for each star you destroyed, and</para></listitem>
 <listitem><para>1 point for each casualty you incurred.</para></listitem>
 </orderedlist>
@@ -1642,14 +1669,25 @@ SST2K website.</para>
 <para>Dave Matuszek, Paul Reynolds et. al. at UT Austin played the
 Hicks version on a CDC6600, but disliked the long load time and
 extreme slowness of the BASIC program. (David Matuszek notes that the
-Hicks version he played had a habit of throwing long
-quotes from Marcus Aurelius at the users, a feature he found
-intolerable on a TTY at 110 baud.  It must, therefore, have been
-rather longer than  the one we have.)  The Austin crew proceeded to
-write their own Trek game, loosely based on the Hicks version, in
-CDC6600 FORTRAN.  At that time, it was just called "Star Trek"; the
-"Super" was added by later developers. In the rest of this history
-we'll call it the "UT FORTRAN" version.</para>
+Hicks version he played had a habit of throwing long quotes from
+Marcus Aurelius at the users, a feature he found intolerable on a TTY
+at 110 baud.  It must, therefore, have been rather longer than the one
+we have.)</para>
+
+<para>The Austin crew proceeded to write their own Trek game, loosely
+based on the Hicks version, in CDC6600 FORTRAN.  Most of the code was
+written in 1973-1974. At that time, the game was just called "Star
+Trek"; the "Super" was added by later developers. In the rest of this
+history we'll call it the "UT FORTRAN" version.</para>
+
+<para>Dave Matuszek reports that the UT FORTRAN codebase he worked on
+in 1973-1974 was like Mayfield's original and most later versions in
+BASIC, in that it used used polar coordinates (a clockface angle
+and a distance) for manual navigation.</para>
+
+<para>Tom Almy writes: "I've received further information that the
+black holes, Tholian web, Super Commander, and Emeritus mode were
+added by Marc Newman."</para>
 
 <para>At the time the UT FORTRAN source was last translated to C it emitted
 the message "Latest update-21 Sept 78".  Thus, it actually predated
@@ -1657,13 +1695,13 @@ the message "Latest update-21 Sept 78".  Thus, it actually predated
 Star Trek" published by David Ahl in his November 1978 sequel
 <citetitle>BASIC Computer Games</citetitle>.</para>
 
-<para>This 1978 "Super Star Trek" had been reworked by Robert Leedom and
-friends from (according to Leedom) Mayfield's HP port. There is
+<para>This 1978 "Super Star Trek" had been reworked by Robert Leedom
+and friends from (according to Leedom) Mayfield's HP port. There is
 internal evidence to suggest that at least some features of Leedom's
 SST may have derived from the UT FORTRAN version.  In particular, Dave
 Matuszek recalls implementing command words to replace the original
-numeric command codes, a feature Leedom's SST also had but the
-1973 and 1975 SPACWRs did not.</para>
+numeric command codes during 1973-1974, a feature Leedom's SST also
+had but the 1973 and 1975 SPACWRs did not.</para>
 
 <para>One signature trait of the UT FORTRAN game and its descendants
 is that the sectors are 10x10 (rather than the 8x8 in Mike Mayfield's
@@ -1672,9 +1710,6 @@ preserves the original numbered quadrants rather than the
 astronomically-named quadrants introduced in Ahl's SST and its
 descendants.</para>
 
-<!-- Dave thinks his Fortran Star Trek used the clockface for quadrant -->
-<!-- navigation. -->
-
 <para>Eric Allman's BSD Trek game is one of these, also descended from
 the UT FORTRAN version via translation to C.  However, the mainline version
 (now SST2K) has had a lot more stuff folded into it over the years
@@ -1849,7 +1884,7 @@ 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've cleaned up a lot of grubby FORTRANisms in the code internals --
+I've cleaned up a lot of grubby FORTRANisms in the code internals &mdash;
 used sizeof(), replaced magic numeric constants with #defines,
 that sort of thing.
 </para></listitem>
@@ -1919,6 +1954,9 @@ derived from a still earlier version in use at Penn State University.</para>
 </sect1>
 <sect1><title>References</title>
 
+<para>These are the original references by Dave Matuszek and Paul
+Reynolds:</para>
+
 <orderedlist>
 <listitem><para><citetitle>Star Trek</citetitle> (the original television
 series), produced and directed by Gene Rodenberry.</para></listitem>
@@ -1938,9 +1976,9 @@ Books)</para></listitem>
 David Gerrold.  Similiar in scope to the above book.
 (Bantam)</para></listitem>
 
-<listitem><para><citetitle>The Star Trek Guide</citetitle>, third revision 4/17/67, by Gene
-Roddenberry.  The original writer's guide for the television
-series, but less comprehensive than (3) above.
+<listitem><para><citetitle>The Star Trek Guide</citetitle>, third
+revision 4/17/67, by Gene Roddenberry.  The original writer's guide
+for the television series, but less comprehensive than (3) above.
 (Norway Productions)</para></listitem>
 
 <listitem><para><citetitle>The Trouble With Tribbles</citetitle>, by
@@ -1963,4 +2001,66 @@ shops.</para></listitem>
 
 </sect1>
 </chapter>
+
+<appendix><title>Setting the Wayback Machine</title>
+
+<para>SSTK and its ancestors have a long history.  One of the
+objectives of this project is to make that history available.
+Accordingly, here is a timeline of the development of SST2K and
+its ancestors, as closely as we can reconstruct it.  Someday this
+may become the basis for a "wayback machine" switch that enables
+feature sets by year.</para>
+
+<itemizedlist>
+<listitem><para>1971 &mdash; Mike Mayfield's original BASIC Star
+Trek.</para></listitem>
+
+<listitem><para>5 April 1973 &mdash; Grady Hicks's BASIC version fot
+the Taurus.</para></listitem>
+
+<listitem><para>Summer 1973 &mdash; Dave Matuszek, Paul Reynolds, and
+the Austin crew begin work on the UT FORTRAN version.</para></listitem>
+
+<listitem><para>1974 &mdash; Dave Matuszek gets distracted by other
+things, notably a job change and the birth of his first
+child.</para></listitem>
+
+<listitem><para>c.1977 &mdash; Tom Almy translates the UT FORTAN
+version to PDP-11 FORTRAN.</para></listitem>
+
+<listitem><para>21 September 1978 &mdash; This was the date on the
+first version Tom Almy saw, on which he based his C
+translation.</para></listitem>
+
+<listitem><para>1979 &mdash; Marc Newman adds Tholians, black holes,
+super-commanders, and Emeritus mode.</para></listitem>
+
+<listitem><para>1995-1996 &mdash; Tom Almy translates his FORTRAN
+port to ANSI C.</para></listitem>
+
+<listitem><para>1997 &mdash; Tom Almy finds the sources for the UT
+FORTRAN on the Web and merges in features new since the 1978 version:
+EMEXIT, Tholian Web, improved death ray.  He adds deep-space probes
+from the DECUS version.</para></listitem>
+
+<listitem><para>10 October 2004 &mdash; ESR starts hacking on Almy's C
+translation, de-FORTRANIZING the code. HELP/CALL/SOS becomes MAYDAY.
+</para></listitem>
+
+<listitem><para>30 October 2004 &mdash; SST2K project started on
+Berlios.</para></listitem>
+
+<listitem><para>18 January 2005 &mdash; First changes merged in from Stas
+Sergeev. The curses interface is added.</para></listitem>
+
+<listitem><para>September 2006 &mdash; BSD features merged
+in. Inhabited-worlds features and weighted critical hits date from
+this time.</para></listitem>
+</itemizedlist>
+
+<para>One as-yet unanswered question is when the code changed from
+distance/direction navigation to coordinate offsets.  Dave Matuszek
+believes it must have been after he stopped working on the game in
+1974.</para>
+</appendix>
 </book>