[Freeciv-Dev] Documentation improvements, v2.

[Mitch Davis <mjd@xxxxxxxxxxxxxxxx>]

Dear Freeciv Team,

I've taken the suggestions that David made, and updated the
documentation patch I sent out the other day.

I've checked this in by-the-way.  The attached patch is just
so you can see what has changed since the last patch.

Mitch.

diff -x CVS -u -r freeciv-ver/AUTHORS freeciv-ver-2/AUTHORS
--- freeciv-ver/AUTHORS Tue Dec 22 02:11:56 1998
+++ freeciv-ver-2/AUTHORS       Tue Dec 22 02:12:45 1998
@@ -18,12 +18,16 @@
      John Stonebraker <ppaqebb@xxxxxxxxxxxx> (AI)
      David Pfitzner <dwp@xxxxxxxxxxxxxx> (Patches)
      Cedric Tefft <cedric@xxxxxxxxxxxxx>
+     Reinier Post <rp@xxxxxxxxxx>
+     Kris Bubendorfer <Kris.Bubendorfer@xxxxxxxxxxxxx>
      Peter Schaefer <schaefer@xxxxxxxxxxxxxxxxxxxxxxxxxxx>
      Massimo Campostrini <campo@xxxxxxxxxxxxxxxxxxxxx>
+     Sverker Wiberg <sverkerw@xxxxxxxxxxxx>
+     Markus Linnala <maage@xxxxxxxxx>
      Trevor Pering <pering@xxxxxxxxxxxxxxxxxxxxxxxxx>
      Dee Jay Randall <randal@xxxxxxxxxxxxx>
      Kris Bubendorfer <Kris.Bubendorfer@xxxxxxxxxxxxx> (diplomats)
-     Reinier Post <rp@xxxxxxxxxx>
+     Reinier Post <reinpost@xxxxxxxxxx>
      Markus Linnala <maage@xxxxxxxxx>
      Finn Arne Gangstad <finnag@xxxxxxxxxxx>
      Paul Cameron <pmcamero@xxxxxxxxxxxxxxx>
@@ -31,13 +35,13 @@
      Christian Grothoff <ma0035@xxxxxxxxxxxxxxxxxxxxx> (Europe scenario)
      Mirar <mirar@xxxxxxxxx>
      Greg Wooledge <wooledge@xxxxxxxxxxx>
-     Sverker Wiberg <sverkerw@xxxxxxxxxxxx>
+     Falk Hueffner <falk.hueffner@xxxxxxxxxxxxxxxxxxxxxxxx> (Space Race)
      Anthony J. Stuckey <stuckey@xxxxxxxxxxxxxxxxx>
      Patrick Smith <patsmith@xxxxxxxxx>
      Rizos Sakellariou <rizos@xxxxxxxxxxx> 
      Sergey Shkonda <serg@xxxxxxxxx>
      Matthew Hunt <mph@xxxxxxxxx>
-     Mika Korhonen <mikak@xxxxxxxxxxxx>
+     Mika Korhonen <mikak@xxxxxxxxxx>
      Robert Donn <squirk@xxxxxxxxxx>
      Alex Rhomberg <rhomberg@xxxxxxxxxxxxxx>
      Mark Brown <broonie@xxxxxxxxxxxxxxx>
@@ -46,8 +50,8 @@
 
   GTK+ Port:
 
-     Per I Mathisen <permath@xxxxxxxxxxx> (GTK+ port)
-     Vasco Alexandre da Silva Costa <vasc@xxxxxxxxxxxxxxxxxxxxx> (GTK+ port)
+     Per I Mathisen <permath@xxxxxxxxxxx>
+     Vasco Alexandre da Silva Costa <vasc@xxxxxxxxxxxxxxxxxxxxx>
 
   Bug reports and testing:
 
@@ -66,26 +70,41 @@
 
   Mailing list hosting:
 
-     John Goerzen <jgoerzen@xxxxxxxxxxxx> (+java civclient project)
+     John Goerzen <jgoerzen@xxxxxxxxxxxx> (+Java civclient project)
      Ryan Rehder <twolf@xxxxxx> (freeciv.midsun.com: Mar '98 to Nov '98)
 
-  And...
+  These people helped us previous to the 1.7 series:
+
+     James Blackwell <innocent@xxxxxxxxxxxxxxxxxxxxxx> (Docs, co-admin)
+     Olav Andree Brevik <olavb@xxxxxxxxxx>
+     Carl Bartels <cb@xxxxxxxxxxxxxxxxxxxxxxx>
+     Alexander Mai <st002279@xxxxxxxxxxxxxxxxxxxxxx>  (OS/2 patches)
+     Olli Helenius <ollhel@xxxxxxxx>
+     Frank Muzzulini <muzz@xxxxxxxxxxxxxxxxxxxxxx>
+     Seth Golub <seth@xxxxxxxxxxxx>
+     Jake Kesinger <kesinger@xxxxxxxxxxxx>
+     Sam Holden <sholden@xxxxxxxxxxxxxxxxxxxx> (GNU-Win32 patch)
+     Markus L. Noga <ut6e@xxxxxxxxxxxxxxxxxxx>
+
+     Erik Vasaasen (Freeciv motto), Peter Mains (metaserver), Rene
+     Schalburg (startup scripts), Robert H. Forsman Jr (canvas
+     widget), Warwick Allison, Stephan Boettcher, Matthias Gessl,
+     Thomas Kraube, Brian Thomas, Troels Valsted Hansen (Amiga),
+     Peter Skov (help buttons), Peter Meerwald (OS/2), Michael
+     Hohensee (icons, HOWTOPLAY), Rajala Ilkka, Richard Braakman
+     and Jan Echternach.
+
+  And finally...
 
      The guys in the DAIMI labs, who playtested early versions of
      Freeciv for the Great Danes.
 
      The members of the freeciv-dev mailing list, coders and non-
-     coders alike.  You all have valuable comments and contributions.
+     coders alike.  You've all made valuable comments and contributions.
 
      Sid Meier, for slight inspiration ;)
 
-  Note, this list does not include many of the fine people who helped
-  us prior to the release of 1.6.6.  Contributors since 1.5.4 can be
-  found in the ChangeLog file, and contributors prior to that can
-  be found in previous versions of this file, which can be retrieved
-  using CVS from the Freeciv CVS repository.
-
-  If we have missed someone, please accept our apologies and let
-  us know.
+  If we have missed someone or details have changed, please accept our
+  apologies and let us know.
 
                     The Freeciv Team.
diff -x CVS -u -r freeciv-ver/HOWTOPLAY freeciv-ver-2/HOWTOPLAY
--- freeciv-ver/HOWTOPLAY       Sat Dec 12 05:41:03 1998
+++ freeciv-ver-2/HOWTOPLAY     Mon Dec 21 22:07:59 1998
@@ -28,7 +28,7 @@
 do is build cities and explore your island.  You want lots of cities,
 seven or eight at the least.
 
-The name of the game is to tie down as many squares of land as
+        The name of the game is to tie down as many squares of land as
 possible.  When building a city, make sure that you don't overlap too
 much with territory from one of your other cities.  You can see which
 squares are being used by a city by clicking on it.  The map of the
@@ -37,14 +37,15 @@
 further apart they are, the more difficult they are to defend and
 administer at this stage.  (Tip: Try to build on horses or near fish).
 
-       Now that you have a city or two, you'll want to set the
-science rate to 100%.  Don't worry about the tax rate, since you won't
-be building any improvements to drain your cash; you'll be building
-settlers.  Every city should be churning out settlers.  The more
-settlers you make, the more cities you can have; the more cities you
-have, the faster you gain tech; the faster you gain tech, the faster
-you win.  After you have built as many cities as your corner of the
-world will hold, turn the settlers to irrigating and building roads.
+        Now that you have a city or two, you'll want to set the science
+rate as high as your government type will allow.  Don't worry about
+the tax rate, since you won't be building any improvements to drain
+your cash; you'll be building settlers.  Every city should be churning
+out settlers.  The more settlers you make, the more cities you can
+have; the more cities you have, the faster you gain tech; the faster
+you gain tech, the faster you win.  After you have built as many
+cities as your corner of the world will hold, turn the settlers to
+irrigating and building roads.
 
 (Note: If the food production in a city drops to +1 from supporting
 too many settlers, and you can't rearrange people to increase it, then
@@ -53,11 +54,14 @@
 
        All this time, you have been gaining techs as fast as
 possible.  What you should be shooting for is first "The Republic",
-then "Democracy", then "Railroad", and then "Industrialization".  As
-soon as you get The Republic, start a revolution and change over to a
-Republic government.  Cities operate much better as Republics
-than they do under despotisms, but note that it's much harder to
-keep military units outside of city limits under a Republic.
+then "Democracy", then "Railroad", and then "Industrialization".
+(Some people go for The Monarchy before The Republic).  As soon as
+you've researched a new government type, start a revolution and change
+over to it.  Cities operate much better as Republics than they do
+under despotisms, but note that it's much harder to keep military
+units outside of city limits under a Republic.  Also, don't forget to
+recheck your rates after you've changed governments, as the maximums
+vary for each type.
 
        When you get Democracy, you are equipped to go into the Second
 Expansion phase.  This is accomplished by changing the government to a
@@ -79,14 +83,14 @@
 Second Expansion Phase:
 
        When you get your cities to a good sized population, wean them
-off luxuries gradually and increase taxes.  Once they're down to
-30% luxury or so, put as much of the taxes as you can into science,
-while maintaining a positive income.  When you get railroad, turn all
-your roads into rails (Tip: turn every square used by a city into a
-road/rail, it increases that city's output).  
-
-FIXME: Is this still true?  I thought an upgrade of the city
-square to rail was automatic...
+off luxuries gradually and increase taxes.  Once they're down to 30%
+luxury or so, put as much of the taxes as you can into science, while
+maintaining a positive income.  When you get railroad, turn all your
+roads into rails, or at least the squares used for production, or
+those that form part of a transport network.  (Tip: turn every square
+used by a city into a road/rail, it increases that city's output.
+There's no need to upgrade the very centre square - that's done
+automatically).
 
        Now is the time to develop industrialization, and military
 technologies.  You should also begin building cities on other islands,
@@ -97,12 +101,13 @@
 Production Phase:
 
        Now you're building factories and power plants in your cities.
-You want to get as much production as possible out of each city.  
-Pollution becomes a problem.  Try to research "Recycling" as soon as
-possible, so you can build recycling centers.  Once you've got all
-your cities going strong, you must build military units. (Note: If you
-come into contact with another player, you should immediately build a
-few attack units, and at least one defense unit per city.)
+You want to get as much production as possible out of each city.
+Pollution becomes a problem.  As soon as you can, try to research Mass
+Production for Mass Transits, and Recycling so you can build
+Recycling Centers.  Once you've got all your cities going strong, you
+must build military units. (Note: If you come into contact with
+another player, you should immediately build a few attack units, and
+at least one defense unit per city.)
 
        When you want to begin thinking about attacking someone, set
 science to 0%, and put raise taxes as high as you can without
@@ -129,8 +134,9 @@
 Q. What other strategies are there?
 
 Well, you could read "Greggurabi's Twelve Steps to World Domination",
-available at http://FIXME.  It's a detailed guide to winning against
-the AI.
+available at ftp://ftp.freeciv.org/pub/freeciv/contrib/gregurabi.txt
+It's a detailed guide to winning against the AI.  Plus, the Freeciv
+online help describes another strategy.
 
 Q. In multiplayer games, what timeout should I set?
 
@@ -211,7 +217,8 @@
 technologies you need to get first.
 
 Alternatively, you could download David Pfitzner's "techtree" map,
-from http://FIXME.
+from http://msowww.anu.edu.au/~dwp/freeciv/.
+
 
 Failing that, you could read the source in common/tech.c.  It
 shows a list of all the techs, and what techs are necessary to get
@@ -222,12 +229,12 @@
 
    For Attack:
 
-       Tanks (armor), Helicopters, Cruise Missiles, Battleships,
+       Armor (tanks), Helicopters, Cruise Missiles, Battleships,
        Transports, and Nuclears.
 
    For Defense:
 
-       Tanks (armor), Mech Inf. Howitzers, Battleships,
+       Armor (tanks), Mech Inf. Howitzers, Battleships,
        Cruise Missiles, Nuclears.
 
 Remember, the best defense is a strong offense.
diff -x CVS -u -r freeciv-ver/INSTALL freeciv-ver-2/INSTALL
--- freeciv-ver/INSTALL Sat Dec 12 05:43:58 1998
+++ freeciv-ver-2/INSTALL       Tue Dec 22 02:16:14 1998
@@ -15,9 +15,10 @@
 
    The Unix operating system, a work-alike such as Linux or FreeBSD,
    or some OS that provides a very Unix-like personality or mode, like
-   EMX under OS/2 or Cygnus GNU-Win32 under Windows.  Support for
+   EMX under OS/2 or the Cygnus Cygwin toolkit under Windows.
+   (See http://http://sourceware.cygnus.com/cygwin/).  Support for
    BSD-style TCP/IP sockets is essential, as is a Bourne-shell
-   compatible shell.  (Most Unixes fit the bill...)
+   compatible shell, such as GNU "bash".  (Most Unixes fit the bill...)
 
  - X-Windows.
 
@@ -28,8 +29,6 @@
    your system, you may need to use the --x-includes=DIR
    and --x-libraries=DIR options.
 
-   FIXME: Possible to have --x=DIR, like --with-xpm-prefix=DIR?
-
  - The "Athena" widget library.
 
    This library (also known as "Xaw") is usually supplied standard
@@ -41,8 +40,11 @@
    compiling with Xaw3d, then add "--with-xaw3d" to the Freeciv
    configure script.
 
-   FIXME: What happens when Xaw3d is installed on a machine as Xaw??
-   How to work around this?
+   There are also other variants of Xaw, such as Nextaw.  Freeciv
+   does not work with these, although it should be possible to modify
+   it in the same fashion as for Xaw3d.  Another tool which may help
+   is called "xaw_wrappers", although how to use it is beyond the
+   scope of this file.
 
  - The "Xpm" library.
 
@@ -73,17 +75,22 @@
    a C++ compiler.
 
    Development of Freeciv is primarily done with "gcc", the GNU
-   project's excellent C compiler.  Other compilers (such as the
-   unbundled Solaris C compiler) will usually work.
+   project's excellent C compiler.  Releases can be compiled with gcc
+   or most other compilers (such as the unbundled Solaris C compiler).
+   Development releases and CVS snapshots will not work without gcc,
+   unless you give configure the "--disable-cvs-deps" option.  See
+   the section below for more information.
 
  - A "make" program.
 
    Freeciv developers generally use "gmake", the GNU make program.
 
    Officially released versions of Freeciv are designed to have
-   makefiles which work with most make programs.  Development
-   releases and CVS snapshots usually won't, because they contain
-   things which use gmake's enhanced features.
+   makefiles which work with most make programs.  Development releases
+   and CVS snapshots contain things (like dependencies) which use
+   gmake's enhanced features, so gmake is necessary for development,
+   unless you give configure the "--disable-cvs-deps" option.  See the
+   section below for more information.
 
    You can check if you have GNU make installed on your system by
    typing:
@@ -92,8 +99,6 @@
 
    The output should include "GNU Make" somewhere.
 
-   FIXME: Anything else needed here?
-
 1. Generating the Makefile:
 ===========================
 
@@ -117,10 +122,17 @@
 
  % ./configure --help
 
-If you don't have GNU make, then after the configuration you must
-FIXME: what?
-You'll especially need to do this if you're using the Solaris make
-program.
+  If you're compiling a development release or a CVS snapshot, and you
+  don't have both GNU make AND gcc, then pass configure the
+  "--without-cvs-deps" option.  You'll especially need to do this if
+  you're using the Solaris cc and make programs.
+
+  Note that if you do this, dependency checking is disabled.  If you
+  change any Freeciv .h files after this for any reason, you should do
+  a "make clean" before doing "make" to ensure everything is compiled
+  correctly.
+
+  "--disable-cvs-deps" has no effect when run with a stable release.
 
 If you want to change the compiler options, set the CFLAGS environment
 variable in your shell before running "configure".  For example:
@@ -152,12 +164,15 @@
 
   - Let us know, so that we can fix it for the next release!!
 
-    Send mail to <freeciv-dev@xxxxxxxxxxx> telling us what you did,
+    Send mail to the freeciv-dev mailing list, telling us what you did,
     and what the result is.  It would be helpful to include the output
     of the configure script, and the contents of the "config.status",
     "config.cache" and "config.log" files, which are generated by the
     configure script.
 
+    You can find out about the freeciv-dev mailing list on our web
+    site, at http://www.freeciv.org
+
   - If you're still having problems, and you'd like to persist, edit the
 
     "Makefile.noimake" file, then use as follows:
@@ -185,21 +200,23 @@
   - The "client/civclient" and "server/civserver" binaries.
   - The "data/" directory, which contains the graphics and scenarios.
 
-It's perfectly feasible to play Freeciv either as a try-out or
-permanently, in this directory using the "civ" and "ser" scripts.
+It's perfectly feasible to play Freeciv in this directory, without
+installing it.  If you do this, you'll need to use the "civ" and
+"ser" scripts.
+
 See the README file for more information.
 
 3. Installation:
 ================
 
-FIXME: We need to think about an "install" target.
-
 Installing Freeciv involves installing the components mentioned in
 Section 2.  These need to be copied to a directory such as /usr/games,
 /usr/games/freeciv, /usr/local/freeciv, or some other suitable
 directory.
 
-FIXME: Details, details!!
+Typing "make install" should install everything correctly on
+your machine.  You may like to use the --prefix=DIR configure option
+to ensure the files get placed where you want.
 
 When the Freeciv client starts, it looks in the current directory for
 the data/ directory. You can override this by setting the
diff -x CVS -u -r freeciv-ver/README freeciv-ver-2/README
--- freeciv-ver/README  Sat Dec 12 05:49:05 1998
+++ freeciv-ver-2/README        Tue Dec 22 02:19:55 1998
@@ -9,16 +9,18 @@
 locally or over a network, and an AI which gives most people a run for
 their money.
 
-Freeciv aims to be completely rule-compatible with Civilization II[tm],
-published by Sid Meier and Microprose[tm].
+Freeciv aims to be mostly rule-compatible with Civilization II[tm],
+published by Sid Meier and Microprose[tm].  A few rules are different
+where we think it makes more sense, and we have lots and lots of
+adjustable parameters to make customizing games possible.
 
 Freeciv has been implemented completely independently of Civilization;
 you do not need to own Civilization to play Freeciv.
 
 Although the graphics are not as polished as those in Civilisation II,
 the rules are very complete, and our multiplayer and networking code is
-excellent.  At the moment, we lack only alliances and the Space Race.
-(Both are being developed now).
+excellent.  At the moment however, we're lacking alliances and the
+Space Race, although both are being developed now.
 
 Web site:
 =========
@@ -52,11 +54,14 @@
 client programs as there are human players.  The server does not need
 X, but the clients do.
 
-    The following examples assume that the Freeciv "civ" and "ser"
-    programs are in your current PATH.  If they aren't, you'll get
-    messages like "command not found".  You can either set your PATH
-    so it includes the directory where these programs live, or you can
-    prepend the directory to the start of each command.
+    NOTE:
+
+    The following examples assume that Freeciv has been installed on
+    your system, and that the directory containing the "civclient" and
+    "civserver" programs is in your PATH.  If Freeciv is not
+    installed, then you may want to use the "civ" and "ser" programs,
+    which can be found in the top Freeciv directory.  They are used
+    in exactly the same fashion as "civclient" and "civserver".
 
 Running Freeciv involves starting the server, then the client(s)
 and AI(s), then telling the server to start the game.  Here are the
@@ -66,11 +71,11 @@
 
   To start the server:
 
-  % ser
+  % civserver
 
   Or for a list of command-line options:
 
-  % ser --help
+  % civserver --help
 
   Once the server is started, a prompt will appear:
 
@@ -123,12 +128,14 @@
   Now all the human players should join, by running the Freeciv
   client:
 
-  % civ
+  % civclient
+
+  This assumes the server is running on the same machine.  If not, you
+  can either specify it on the command use with the '-server' option,
+  or enter it into the first dialog box once the client starts.
 
-  This assumes the server is running on the same machine.  If not, use
-  the -server option.  For example, suppose the server is running on a
-  different machine called 'neptune'.  Then players would join with a
-  command like:
+  For example, suppose the server is running on a different machine
+  called 'neptune'.  Then players would join with a command like:
 
   % civclient -server neptune
 
@@ -136,20 +143,33 @@
   started.  In standard Unix fashion you can start the client
   "in the background" by appending an ampersand:
 
-  % civ &
+  % civclient &
 
 Computer Players:
 
-  To start an AI player, give the 'create' command to the server.  
-  For example:
+  There are two ways to create AI players.  The first is to
+  set the number of players (human and AI) with the 'aifill'
+  server command.  For example:
+
+  > aifill 7
+
+  After using the "s" server command to start the game, any players
+  which aren't controlled by humans will be AI players.  For the
+  above, if two human players had joined, 5 AI players would be
+  created.
+
+  The second way is to explicitly create an AI with the 'create'
+  server command.  For example:
 
   > create HumanKiller
 
-  This will create an AI-controlled player called HumanKiller.  AI
-  players are assigned to tribes after the human players have chosen
-  their tribes, but you can choose a particular tribe for an AI player
-  by using the normal name for that nation's leader.  For example, to
-  play against AI-controlled Romans, use this server command:
+  This will create an AI-controlled player called HumanKiller.
+
+  AI players are assigned to tribes after all human players have
+  chosen their tribes, but you can choose a particular tribe for an AI
+  player by using the normal name for that nation's leader.  For
+  example, to play against AI-controlled Romans, use this server
+  command:
 
   > create Caesar
 
@@ -209,7 +229,9 @@
 file.
 
 Alternatively, check out "Greggurabi's Twelve Steps to World
-Domination", published on the Freeciv website.
+Domination", which you can find here:
+
+  ftp://ftp.freeciv.org/pub/freeciv/contrib/gregurabi.txt
 
 Ending the game:
 ================
@@ -231,18 +253,17 @@
 
 You can restore a saved game by using the '-f' server option, eg:
 
-  % ser -f oursave2001.sav
+  % civserver -f oursave2001.sav
 
 Now the players can rejoin the game:
 
-  % civ -n Alexander
+  % civclient -n Alexander
   
 Notice how the player-name is specified with the -n option. It's vital
-that the player uses the same name as they originally had, if they're to
-be allowed in.
+that the player uses the same name as they had when the game started,
+if they're to be allowed in.
 
-The game may then be restarted with 's' as usual. Note that additional
-players can join the game, even if it has been restarted.
+The game may then be restarted with 's' as usual.
 
 Server autostart:
 =================
@@ -269,13 +290,13 @@
 all fatal, normal, and debug messages.
 
 Example: 
-        % ser -l my.log -d 2
+        % civserver -l my.log -d 2
 
 This sends all server log messages to file "my.log", including debug
 messages.
 
 Example: 
-        % civ --debug 0
+        % civclient --debug 0
 
 This suppresses all non-fatal client log messages.
 
@@ -287,6 +308,11 @@
 
  - Check the Freeciv website, to ensure you're playing the latest
    version.  (We may have already fixed the problem).
+
+   In particular, you might like to try a developer's napshot,
+   from our CVS repository.  You can FTP them from:
+
+     http://www.freeciv.org/latest.html
 
  - Check the Freeciv FAQ on the Freeciv website to see if we've
    published a way to work around your bug.