[Freeciv-Dev] Re: (PR#11996) incomplete manpage

["Ben Bettin" <bwbettin@xxxxxxxxx>]

<URL: http://bugs.freeciv.org/Ticket/Display.html?id=11996 >

In reviewing the manpages with the information from --help, the
website, sourcecode, and people on irc, it's evident there were a few
options missing from the manpages.  I've updated both the civclient.6
and civserver.6 manpages.  I added all current options, some notes on
different points, added an example and explained the ones that were
there, updated the file listings, etc.

The attached patch is an update to the files from the cvs snapshot on
2005-01-24 10:34:30 (freeciv-cvs-Jan-23.tar.bz2).

This is the first patch I've ever created, so I'm listing the commands
I used to create it below so someone can inform me if I did it
incorrectly.

diff -u civclient.6.orig civclient.6 >> manpages-cvs_Jan_23.diff
diff -u civserver.6.orig civserver.6 >> manpages-cvs_Jan_23.diff


-Ben Bettin



On Sun, 23 Jan 2005 15:09:23 -0800, Jason Short
<jdorje@xxxxxxxxxxxxxxxxxxxxx> wrote:
> 
> <URL: http://bugs.freeciv.org/Ticket/Display.html?id=11996 >
> 
> The -s server command-line parameter isn't in the manpage.
> 
> -jason
> 
>

--- civclient.6.orig    2005-01-23 01:32:38.000000000 -0500
+++ civclient.6 2005-01-24 22:37:54.000000000 -0500
@@ -9,16 +9,24 @@
 .\"   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\"   GNU General Public License for more details.
 .\"
-.TH FREECIV 6 "July 1st 2004"
+.TH FREECIV 6 "January 24th 2005"
 .SH NAME
 civclient \- The client for the Freeciv game
 .SH SYNOPSIS
 .B civclient \
-[ \-a|\-\-autoconnect ] [ \-d|\-\-debug \fIlevel\fP ] [ \-h|\-\-help ] \
-[ \-l|\-\-log \fIlogfile\fP ] [ \-m|\-\-meta \fIserver\fP ] \
-[ \-n|\-\-name \fIname\fP ] [ \-p|\-\-port \fIport\fP ] \
-[ \-P|\-\-Plugin \fIplugin\fP ] [ \-s|\-\-server \fIserver\fP ] \
-[ \-S|\-\-Sound \fItags\fP ] [ \-t|\-\-tiles \fItiles\fP ] [ \-v|\-\-version ]
+[ \-a|\-\-autoconnect ] \
+[ \-d|\-\-debug \fIlevel_number\fP ] \
+[ \-h|\-\-help ] \
+[ \-l|\-\-log \fIfilename\fP ] \
+[ \-m|\-\-meta \fIaddress\fP ] \
+[ \-n|\-\-name \fIstring\fP ] \
+[ \-p|\-\-port \fIport\fP ] \
+[ \-P|\-\-Plugin \fIstring\fP ] \
+[ \-r|\-\-read \fIfilename\fP ] \
+[ \-s|\-\-server \fIaddress\fP ] \
+[ \-S|\-\-Sound \fIfilename\fP ] \
+[ \-t|\-\-tiles \fIstring\fP ] \
+[ \-v|\-\-version ]
 .SH DESCRIPTION
 Freeciv is a free turn-based multiplayer strategy game, in which each player
 becomes the leader of a civilization, fighting to obtain the ultimate goal:
@@ -51,54 +59,86 @@
 their effects are identical.
 .TP
 .BI "\-a, \-\-autoconnect"
-Skips the connect dialog, automatically inserts the default values. This is
+Skips the connect dialog, automatically inserting the default values. This is
 quite convenient when all has been set up properly.
 .TP
-.BI "\-d, \-\-debug"
-Sets the debug log level (0 to 3) of information to be logged. Use the
+.BI "\-d \fIlevel_number\fP, \-\-debug \fIlevel_number\fP"
+Sets the amount of debugging information to be logged in the file named by the
 .I \-l
-option to send the logging to a file.
+option. Acceptable values for the \fIlevel_number\fP are:
+
+\fB0\fP    for fatal messages only.
+
+\fB1\fP    for fatal and error messages.
+
+\fB2\fP    for fatal, error and normal messages.
+
+\fB3\fP    for fatal, error, normal, and verbose messages.
+
 .TP
 .BI "\-h, \-\-help"
-Prints a short summary of the options.
+Prints a short summary of the command line options.
 .TP
-.BI "\-l, \-\-log"
-Specifies the file to be used as a logfile for logging. Use the
+.BI "\-l \fIfilename\fP, \-\-log \fIfilename\fP"
+Defines a log file, \fIfilename\fP, to be produced during processing. Use the
 .I \-d
-option to set the amount of loggin.
+option to set how much is logged.  By default, fatal and normal messages are 
+printed to standard output.  With a log file, such messages go to the log
+instead.
 .TP
-.BI "\-m, \-\-meta"
-Connect to the given metaserver, a place where Freeciv servers can publish 
their
-presence. Freeciv clients consult the metaserver to offer users a selection of
-games to join.
+.BI "\-m \fIaddress\fP, \-\-meta \fIaddress\fP"
+Specifies the \fIaddress\fP of the metaserver to connect to. A metaserver is a
+place where Freeciv servers can publish their presence. Freeciv clients consult
+the metaserver to offer users a selection of games to join. By default the 
+standard Freeciv metaserver is used. 
 .TP
-.BI "\-n, \-\-name"
-Specifies the name to play under. This option is critical when reconnecting to
-a game. Please note that you might need to quote your playername.
+.BI "\-n \fIstring\fP, \-\-name \fIstring\fP"
+Specifies the name (\fIstring\fP) to play under. This option is critical when 
+reconnecting to a game. Please note that you might need to quote your 
playername.
 .TP
-.BI "\-p, \-\-port"
-Specifies the server port to connect to. By default this is 5555, if in doubt
-ask the server administrator.
+.BI "\-p \fIport\fP, \-\-port \fIport\fP"
+Specifies the server \fIport\fP to connect to. By default this is 5555, if in 
+doubt ask the server administrator.
 .TP
-.BI "\-P, \-\-Plugin"
-Specifies to use one of [none, esd, sdl] for sound output.
+.BI "\-P \fIstring\fP, \-\-Plugin \fIstring\fP"
+Specifies the plugin to use for sound output.  Available options  for 
+\fIstring\fP are:
+
+\fBnone\fP
+
+\fBesd\fP
+
+\fBsdl\fP
+
+.TP
+.BI "\-r \fIfilename\fP, \-\-read \fIfilename\fP"
+Specifies a file, \fIfilename\fP, of server commands which the server will 
+automatically read and process, as if you had typed them in at the server's 
+prompt. (for spawned server only)
 .TP
-.BI "\-s, \-\-server"
-The game server to connect to. This server might easily run on the same machine
-as the client.
+.BI "\-s \fIaddress\fP, \-\-server \fIaddress\fP"
+Specifies the game server \fIaddress\fP to connect to. This server might easily
+run on the same machine as the client.
 .TP
-.BI "\-S, \-\-Sound"
-Specifies where to read the sound tags from.
+.BI "\-S \fIfilename\fP, \-\-Sound \fIfilename\fP"
+Specifies the \fIfilename\fP to read the sound tags from.
 .TP
-.BI "\-t, \-\-tiles"
-Indicates a tilespec to be used for tiles within the game.
+.BI "\-t \fIstring\fP, \-\-tiles \fIstring\fP"
+Specifies the tiles to be used within the game by supplying the name 
+(\fIstring\fP) of the tilespec. See the \fIFILES\fP section below for tilespecs
+included with this distribution.
 .TP
 .BI "\-v, \-\-version"
-Prints the version number.
+Prints the version number and exits.
 .SH "EXAMPLES"
-civclient \-\-name "King Richard" \-\-server io.daimi.aau.dk
-
-civclient \-a \-t trident
+.TP
+.B civclient \-\-name "King Richard" \-\-server io.daimi.aau.dk
+Starts the client using the name \fIKing Richard\fP and connecting to the
+server at \fIio.daimi.aau.dk\fP.
+.TP
+.B civclient \-a \-t trident
+Starts the client with the \fItrident\fP tiles and autoconnects to the 
+\fIlocalhost\fP.
 .SH FILES
 .TP
 .BI ~/.civclientrc
@@ -111,6 +151,9 @@
 by default. Currently the following tilespecs can be used:
 
 \(bu
+.I isophex.tilespec
+
+\(bu
 .I isotrident.tilespec
 
 \(bu
@@ -137,7 +180,7 @@
 .SH BUGS
 Please report bugs to
 .UR
-http://rt.freeciv.org/
+http://bugs.freeciv.org/
 .UE
 \.
 .SH "MORE INFO"
@@ -151,9 +194,12 @@
 .SH AUTHORS
 The Freeciv Team <freeciv-dev AT freeciv.org>.
 
-This manpage was put together by Florian Ernst <florian_ernst AT gmx.net> using
-the Client Manual and the comments in the sourcecode. Feel free to use it as
-you wish.
+This manpage was originally put together by Florian Ernst 
+<florian_ernst AT gmx.net> using the Client Manual and the comments in the 
+sourcecode. It was updated by Ben Bettin <bwbettin AT gmail.com> to add new
+features, integrate information from the website's online documentation, and 
+for slight formatting adjustments. Feel free to use it as you wish.
+
 .SH "SEE ALSO"
 .IR civserver (6)
 and the Client Manual at the Freeciv homepage.
--- civserver.6.orig    2005-01-23 01:32:38.000000000 -0500
+++ civserver.6 2005-01-24 18:32:04.000000000 -0500
@@ -9,17 +9,29 @@
 .\"   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\"   GNU General Public License for more details.
 .\"
-.TH FREECIV 6 "July 1st 2004"
+.TH FREECIV 6 "January 24th 2005"
 .SH NAME
 civserver \- The server for the Freeciv game
 .SH SYNOPSIS
 .B civserver \
-[ \-b|\-\-bind \fIaddress\fP ] [ \-d|\-\-debug \fIlevel\fP ] \
-[ \-f|\-\-file \fIsavegame\fP ] [ \-g|\-\-gamelog \fIgamelog\fP ] [ 
\-h|\-\-help ] \
-[ \-i|\-\-info \fIinfo\fP ] [ \-l|\-\-log \fIlogfile\fP ] [ \-m|\-\-meta ] \
-[ \-M|\-\-Metaserver \fIserver\fP ] [ \-p|\-\-port \fIport\fP ] \
-[ \-q|\-\-quitidle \fIseconds\fP ] [ \-e|\-\-exit\-on\-end ] \
-[ \-r|\-\-read \fIfile\fP ] [ \-v|\-\-version ]
+[ \-a|\-\-auth ] \
+[ \-b|\-\-bind \fIaddress\fP ] \
+[ \-d|\-\-debug \fIlevel_number\fP ] \
+[ \-e|\-\-exit\-on\-end ] \
+[ \-f|\-\-file \fIfilename\fP ] \
+[ \-G|\-\-Guests ] \
+[ \-g|\-\-gamelog \fIfilename\fP ] \
+[ \-h|\-\-help ] \
+[ \-l|\-\-log \fIfilename\fP ] \
+[ \-M|\-\-Metaserver \fIaddress\fP ] \
+[ \-m|\-\-meta ] \
+[ \-N|\-\-Newusers ] \
+[ \-p|\-\-port \fIport\fP ] \
+[ \-q|\-\-quitidle \fItime\fP ] \
+[ \-r|\-\-read \fIfilename\fP ] \
+[ \-S|\-\-Serverid \fIid\fP ] \
+[ \-s|\-\-saves \fIdirectory\fP ] \
+[ \-v|\-\-version ]
 .SH DESCRIPTION
 Freeciv is a free turn-based multiplayer strategy game, in which each player
 becomes the leader of a civilization, fighting to obtain the ultimate goal:
@@ -45,69 +57,139 @@
 .SH OPTIONS
 The following options are accepted on the command line of the server. They may
 not be combined; that is, "civserver \-fp savegame.sav 555" will not work,
-instead you would need to enter "civserver \-f savegame.sav \-p 555". All 
options
-have a short form (single hyphen and single letter) and a long form (double
-hyphen and a complete word); their effects are identical.
+instead you would need to enter "civserver \-f savegame.sav \-p 555". All
+options have a short form (single hyphen and single letter) and a long form
+(double hyphen and a complete word); their effects are identical.
 .TP
-.BI "\-b, \-\-bind"
-Sets the address on which the server will listen for clients.
+.BI "\-a, \-\-auth"
+Enables server authentication and allows access to registered players only.
 .TP
-.BI "\-d, \-\-debug"
+.BI "\-b \fIaddress\fP, \-\-bind \fIaddress\fP"
+Sets the \fIaddress\fP on which the server will listen for clients.
+.TP
+.BI "\-d \fIlevel_number\fP, \-\-debug \fIlevel_number\fP"
 Sets the amount of debugging information to be logged in the file named by the
 .I \-l
-option. The number should be 0 for fatal errors only, 1 for fatal and normal
-messages, 2 for fatal, normal, and debugging messages, or 3 for very verbose
-output.
-.TP
-.BI "\-f, \-\-file"
-Loads a saved game into the server before initialization, instead of starting a
-new game. This is for reloading saved games, or for loading scenarios.
-.TP
-.BI "\-g, \-\-gamelog"
-Defines a log file to be produced during processing. This is a game progress
-log of game-related events recording the activities of the players.
+option. Acceptable values for the \fIlevel_number\fP are:
+
+\fB0\fP    for fatal messages only.
+
+\fB1\fP    for fatal and error messages.
+
+\fB2\fP    for fatal, error and normal messages.
+
+\fB3\fP    for fatal, error, normal, and verbose messages.
+
+.TP
+.BI "\-e, \-\-exit\-on\-end"
+When a game ends, exit instead of restarting.
+.TP
+.BI "\-f \fIfilename\fP, \-\-file \fIfilename\fP"
+Loads a saved game (\fIfilename\fP) into the server before initialization,
+instead of starting a new game. This is for reloading saved games, or for 
+loading scenarios. The distribution comes with such scenarios, typically stored
+in \fI/usr/local/share/freeciv/scenario\fP:
+
+.IP
+\(bu
+.I british\-isles\-85x80\-v2.80.sav
+
+\(bu
+.I earth\-160x90\-v2.sav
+
+\(bu
+.I earth\-80x50\-v2.sav
+
+\(bu
+.I europe\-200x100\-v2.sav
+
+\(bu
+.I hagworld\-120x60\-v1.2.sav
+
+\(bu
+.I iberian\-peninsula\-136x100\-v1.0.sav
+
+.TP
+.BI "\-G, \-\-Guests"
+Allow guests to login as 'guest' when authentication is enabled.
+.TP
+.BI "\-g \fIfilename\fP, \-\-gamelog \fIfilename\fP"
+Defines a log file, \fIfilename\fP, to be produced during processing. This is a
+game progress log of game-related events recording the activities of the
+players.
 .TP
 .BI "\-h, \-\-help"
 Prints out a description of the command line options and exits.
 .TP
-.BI "\-i, \-\-info"
-Extra info to be sent to the metaserver.
-.TP
-.BI "\-l, \-\-log"
-Defines a log file to be produced during processing. Use the
+.BI "\-l \fIfilename\fP, \-\-log \fIfilename\fP"
+Defines a log file, \fIfilename\fP, to be produced during processing. Use the
 .I \-d
-option to set how much is logged.
+option to set how much is logged.  By default, fatal and normal messages are 
+printed to standard output.  With a log file, such messages go to the log
+instead.
+.TP
+.BI "\-M \fIaddress\fP, \-\-Metaserver \fIaddress\fP"
+Specifies the \fIaddress\fP of the metaserver to send your server's information
+to. 
 .TP
 .BI "\-m, \-\-meta"
 Directs the server to communicate with a metaserver, a place where Freeciv
 servers can publish their presence. Freeciv clients consult the metaserver to
-offer users a selection of games to join.
-.TP
-.BI "\-M, \-\-Metaserver"
-Sets the metaserver address.
+offer users a selection of games to join. By default the standard Freeciv 
+metaserver is used. You may specify an alternate metaserver with the \fI\-M\fP
+option.
+.TP
+.BI "\-N, \-\-Newusers"
+Allow new users to login and be registered in the players base if 
authentication
+is enabled.
 .TP
-.BI "\-p, \-\-port"
-Specifies the TCP port number to which clients will connect; players must know
+.BI "\-p \fIport\fP, \-\-port \fIport\fP"
+Specifies the TCP \fIport\fP number to which clients will connect; players 
must know
 this number to be able to connect if they are not to use the default of 5555
 decimal. You may need to use this if 5555 is not available for your use on your
-system.
+system, or if you would like to run multiple servers on the same system.
 .TP
-.BI "\-q, \-\-quitidle"
-Quit if no players present for the given number of seconds.
-.TP
-.BI "\-e, \-\-exit\-on\-end"
-When a game ends, exit instead of restarting.
-.TP
-.BI "\-r, \-\-read"
-Specifies a file of server commands which the server will automatically read 
and
-process, as if you had typed them in at the server's prompt.
+.BI "\-q \fItime\fP, \-\-quitidle \fItime\fP"
+Quits if no players are present for the specified \fItime\fP, in seconds, and 
+restarts a new server.
+.TP
+.BI "\-r \fIfilename\fP, \-\-read \fIfilename\fP"
+Specifies a file, \fIfilename\fP, of server commands which the server will 
+automatically read and process, as if you had typed them in at the server's 
+prompt. The distribution comes with a few examples that set options to be 
+similar to Civilization I\*R and Civilization II\*R . The files are named 
+\fIciv1.serv\fP and \fIciv2.serv\fP, and are typically found at 
+\fI/usr/local/share/freeciv/\fP.
+.TP
+.BI "\-S, \-\-Serverid \fIid\fP"
+Sets the server \fIid\fP.
+.TP
+.BI "\-s \fIdirectory\fP, \-\-saves \fIdirectory\fP"
+Specifies the \fIdirectory\fP to place save game files created by the server.
+This is especially useful when you're running more than one server on the same
+system, as it inhibits your servers from clobbering other's save game files.
 .TP
 .BI "\-v, \-\-version"
 Causes the server to display its version number and exit.
 .SH EXAMPLES
-civserver \-\-file oldgame.sav \-\-port 2244
-
-civserver \-g gamelog \-l logfile \-r script \-f oldgame.sav.gz
+.TP
+.B civserver \-\-file oldgame.sav \-\-port 2244
+Starts a server on port \fI2244\fP, loading the save game file 
+\fIoldgame.sav\fP.
+.TP
+.B civserver \-g gamelog \-l logfile \-r script \-f oldgame.sav.gz -p 2244
+Starts a server on port \fI2244\fP, loading the save game file 
+\fIoldgame.sav.gz\fP. Game related events are written to \fIgamelog\fP, other 
+logging information is written to \fIlogfile\fP. When the server starts, it 
+immediately executes the commands contained in \fIscript\fP.
+.TP
+.B civserver -m -a -q 60 -p 2244 -d 2 -l logfile -r script -s ~/saves
+Starts a server on port \fI2244\fP with authentication enabled and 
communicates 
+its existence to the standard Freeciv metaserver. Fatal, error, and normal 
+messages are written to \fIlogfile\fP. When the server starts it immediately 
+executes the commands contained in \fIscript\fP. Save game files are stored in 
+the \fI~/saves\fP directory. When there are no users on the server for \fI60\fP
+seconds, the server will restart.
 .SH COMMANDS
 You may enter commands into the server at any time, either before or during the
 running of a game. 
@@ -123,14 +205,31 @@
 .I default/buildings.ruleset
 
 \(bu
+.I default/cities.ruleset
+
+\(bu
+.I default/game.ruleset
+
+\(bu
+.I default/governments.ruleset
+
+\(bu
+.I default/nations.ruleset
+
+\(bu
 .I default/techs.ruleset
 
 \(bu
+.I default/terrain.ruleset
+
+\(bu
 .I default/units.ruleset
 
 These are the default rule sets used for the game. Alternate sets of rules can
-be installed with the option settings "techs", "units", and "buildings", each 
of
-which provides a name to replace the directory name "default".
+be used by placing them in a separate directory and using the \fBrulesetdir\fP
+command to change your server's ruleset directory. 
+
+Type \fBhelp rulesetdir\fP for more information.
 .SH ENVIRONMENT
 The Freeciv server accepts these environment variables:
 .TP
@@ -156,7 +255,7 @@
 .SH BUGS
 Please report bugs to
 .UR
-http://rt.freeciv.org/
+http://bugs.freeciv.org/
 .UE
 \.
 .SH "MORE INFO"
@@ -170,9 +269,11 @@
 .SH AUTHORS
 The Freeciv Team <freeciv-dev AT freeciv.org>.
 
-This manpage was put together by Florian Ernst <florian_ernst AT gmx.net> using
-the Server Manual and the comments in the sourcecode. Feel free to use it as
-you wish.
+This manpage was originally put together by Florian Ernst 
+<florian_ernst AT gmx.net> using the Server Manual and the comments in the 
+sourcecode. It was updated by Ben Bettin <bwbettin AT gmail.com> to add new
+features, integrate information from the website's online documentation, and 
+for slight formatting adjustments. Feel free to use it as you wish.
 .SH "SEE ALSO"
 .IR civclient (6)
 and the Server Manual on the Freeciv homepage.