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

["Ben Bettin" <bwbettin@xxxxxxxxx>]

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

We originally noticed the problems with the manpages while using
version 2.0.0 beta 7.  I'm not sure what the policy is on patching
released versions, but I thought I'd go ahead and submit a patch for
your consideration for the current beta 7 release.

The patch was created for the beta 7 release as listed on the
freeciv.org website on Jan 20th 2005. 
(ftp://ftp.freeciv.org/freeciv/beta/freeciv-2.0.0-beta7.tar.gz)

Since this is only the second patch I've created (see previous email),
I'm including the commands I used to create so someone can inform me
if I've done it incorrectly.

diff -u civclient.6.orig civclient.6 >> manpages-2.0.0_beta7.diff
diff -u civserver.6.orig civserver.6 >> manpages-2.0.0_beta7.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    2004-07-14 15:16:24.000000000 -0400
+++ civclient.6 2005-01-24 23:18:39.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:
@@ -45,60 +53,92 @@
 .I civclient
 accepts all of the standard X Toolkit command line options along with the
 additional options listed below. Those may not be combined; that is,
-"civclient -np caesar 5556" will not work, instead you would need to enter
-"civclient -n caesar -p 5556". All options have a short form (single
+"civclient \-np caesar 5556" will not work, instead you would need to enter
+"civclient \-n caesar \-p 5556". 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 "-a, --autoconnect"
-Skips the connect dialog, automatically inserts the default values. This is
+.BI "\-a, \-\-autoconnect"
+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
-.I -l
-option to send the logging to a file.
-.TP
-.BI "-h, --help"
-Prints a short summary of the options.
-.TP
-.BI "-l, --log"
-Specifies the file to be used as a logfile for logging. Use the
-.I -d
-option to set the amount of loggin.
-.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.
-.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.
-.TP
-.BI "-p, --port"
-Specifies the server port 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.
-.TP
-.BI "-s, --server"
-The game server to connect to. This server might easily run on the same machine
-as the client.
+.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. 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 "-S, --Sound"
-Specifies where to read the sound tags from.
+.BI "\-h, \-\-help"
+Prints a short summary of the command line options.
 .TP
-.BI "-t, --tiles"
-Indicates a tilespec to be used for tiles within the game.
+.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.  By default, fatal and normal messages are 
+printed to standard output.  With a log file, such messages go to the log
+instead.
 .TP
-.BI "-v, --version"
-Prints the version number.
-.SH "EXAMPLES"
-civclient --name "King Richard" --server io.daimi.aau.dk
+.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 \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 \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 \fIstring\fP, \-\-Plugin \fIstring\fP"
+Specifies the plugin to use for sound output.  Available options  for 
+\fIstring\fP are:
+
+\fBnone\fP
+
+\fBesd\fP
 
-civclient -a -t trident
+\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 \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 \fIfilename\fP, \-\-Sound \fIfilename\fP"
+Specifies the \fIfilename\fP to read the sound tags from.
+.TP
+.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 and exits.
+.SH "EXAMPLES"
+.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    2004-07-14 15:16:24.000000000 -0400
+++ civserver.6 2005-01-24 23:18:39.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:
@@ -44,70 +56,140 @@
 as well as the documentation which is part of the Freeciv distribution.
 .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.
+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.
 .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.
+.I \-l
+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 out a description of the command line options and exits.
+.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 "-i, --info"
-Extra info to be sent to the metaserver.
+.BI "\-h, \-\-help"
+Prints out a description of the command line options and exits.
 .TP
-.BI "-l, --log"
-Defines a log file to be produced during processing. Use the
-.I -d
-option to set how much is logged.
+.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.  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"
+.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.
+.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 "-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.
-.TP
-.BI "-v, --version"
+.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.