improved man page

[chaz/yoink] / doc / yoink.6.in

diff --git a/doc/yoink.6.in b/doc/yoink.6.in
index 2432bd5de9d39abdcdaf847bd69e7759b89e2d6c..5b37c38e78e1ab322d9e895bd2f23e1b0cfbd8ab 100644 (file)
--- a/doc/yoink.6.in
+++ b/doc/yoink.6.in
@@ -2,254 +2,219 @@
 .\" Copyright (c) 2009, Charles McGarvey
 .\" All rights reserved.
 .\" 
 .\" Copyright (c) 2009, Charles McGarvey
 .\" All rights reserved.
 .\" 

-.\" Redistribution   and   use  in  source  and  binary  forms,  with or without
-.\" modification, are permitted provided that the following conditions are met:
+.\" Redistribution  and  use  in  source  and binary forms, with or without
+.\" modification,  are permitted provided that the following conditions are
+.\" met:

 .\" 
 .\" 

-.\"   * Redistributions  of  source code must retain the above copyright notice,
-.\"     this list of conditions and the following disclaimer.
-.\"   * Redistributions  in  binary  form  must  reproduce  the  above copyright
-.\"    notice,  this  list  of  conditions  and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
+.\" 1. Redistributions  of  source  code  must  retain  the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions  in  binary  form must reproduce the above copyright
+.\"    notice,  this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+.\" IS"  AND  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO,  THE  IMPLIED  WARRANTIES  OF  MERCHANTABILITY  AND  FITNESS  FOR A
+.\" PARTICULAR  PURPOSE  ARE  DISCLAIMED.  IN  NO EVENT SHALL THE COPYRIGHT
+.\" OWNER  OR  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL,  EXEMPLARY,  OR  CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT  NOT
+.\" LIMITED  TO,  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA,  OR  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY  OF  LIABILITY,  WHETHER  IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING  NEGLIGENCE  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+.\" OF  THIS  SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 .\" 
 .\" 

-.\" THIS  SOFTWARE  IS  PROVIDED  BY  THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-.\" IS"  AND  ANY  EXPRESS  OR  IMPLIED  WARRANTIES,  INCLUDING, BUT NOT LIMITED
-.\" TO,  THE  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE   ARE  DISCLAIMED.  IN  NO  EVENT  SHALL  THE  COPYRIGHT  HOLDER  OR
-.\" CONTRIBUTORS  BE  LIABLE  FOR  ANY  DIRECT,  INDIRECT,  INCIDENTAL, SPECIAL,
-.\" EXEMPLARY,   OR  CONSEQUENTIAL  DAMAGES  (INCLUDING,  BUT  NOT  LIMITED  TO,
-.\" PROCUREMENT  OF  SUBSTITUTE  GOODS  OR  SERVICES;  LOSS  OF  USE,  DATA,  OR
-.\" PROFITS;  OR  BUSINESS  INTERRUPTION)  HOWEVER  CAUSED  AND ON ANY THEORY OF
-.\" LIABILITY,  WHETHER  IN  CONTRACT,  STRICT  LIABILITY,  OR  TORT  (INCLUDING
-.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
-.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 .\"
 .\"

-.hy

 .TH YOINK 6 "July 24, 2009"
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS
 .TH YOINK 6 "July 24, 2009"
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS

-.B yoink [-h|--help] [OPTION=VALUE]...
-.br
+.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...

 .SH DESCRIPTION
 .SH DESCRIPTION

-.PP

 Leap tall buildings!  Crush stupid robots beneath your feet!  Wield your
 extra-terrestrial powers in the defence of humanity, and send those alien
 invaders back from whence they came!  This is Yoink.
 Leap tall buildings!  Crush stupid robots beneath your feet!  Wield your
 extra-terrestrial powers in the defence of humanity, and send those alien
 invaders back from whence they came!  This is Yoink.

-.PP
-You play the part of a flying alien heroine who must defend her home on Earth
-from other airborne alien invaders.  The game draws inspiration from classic
-arcade games like Joust, Bombjack, Rampage, and Defender--simple, fast-moving
-action.  Basic arguments include:
+
+You play the part of a flying alien heroine who must defend her home on
+Earth from other airborne alien invaders.  The game draws inspiration from
+classic arcade games like Joust, Bombjack, Rampage, and Defender--simple,
+fast-moving action.  Basic arguments include:

 .TP
 .B -h, --help
 .TP
 .B -h, --help

-Display this help and exit.
-.br
+Display basic usage information, and exit immediately.
+.TP
+.B -i, --info
+Display build and environment details, and exit immediately.

 .SH TIPS
 .SH TIPS

-.PP

 To attack, you must dive on the enemy at high speed.  If you're going too
 slowly, you'll just drift harmlessly by.  Diving from above gives different
 To attack, you must dive on the enemy at high speed.  If you're going too
 slowly, you'll just drift harmlessly by.  Diving from above gives different

-results from swooping in and hitting them from the side.  If you're too close to
-attack, try to build up speed by running away and bouncing off a nearby
-building!
-.PP
-By charging your special alien powers, you can throw fireballs.  The orange bar
-at the top of the screen represents your power level--at maximum, you can
-destroy almost anything.  Aiming can be tricky, but with a little practice it's
-quite easy to launch them in the right direction.  Try doing a little swoop or
-circle in the air to line yourself up before releasing your fireball.
-.PP
+results from swooping in and hitting them from the side.  If you're too
+close to attack, try to build up speed by running away and bouncing off a
+nearby building!
+
+By charging your special alien powers, you can throw fireballs.  The orange
+bar at the top of the screen represents your power level--at maximum, you
+can destroy almost anything.  Aiming can be tricky, but with a little
+practice it's quite easy to launch them in the right direction.  Try doing
+a little swoop or circle in the air to line yourself up before releasing
+your fireball.
+

 The heroine has limited energy, measured by the blue bar at the top of the
 screen.  When it runs out, it's game over!  She can regain lost energy by
 picking up bonuses dropped by enemies.
 The heroine has limited energy, measured by the blue bar at the top of the
 screen.  When it runs out, it's game over!  She can regain lost energy by
 picking up bonuses dropped by enemies.

-.PP
-To complete the current attack wave, you must destroy all the enemies.  Hunt
-around, especially in the sky, if you can't find the last few.
-.br
+
+To complete the current attack wave, you must destroy all the enemies.
+Hunt around, especially in the sky, if you can't find the last few.

 .SH OPTIONS
 .SH OPTIONS

-.PP
-There are a plethora of options available for tweaking various aspects of the
-game.  All options can be set either from a configuration file or by passing
-them as arguments.
-.PP
-A
-.B yoink
-configuration file ("yoinkrc") consists of key-value pairs.  The format is not
-unlike that of other configuration files you are already familiar with.  The
-syntax used is lua.
-.B yoink
-looks for configuration files and loads them in this order, the options from
-each subsequent configuration files taking precedence over the same options from
-previous files.
-.TP
-1. @DATADIR@/yoinkrc
-This is the base configuration file which should be considered read-only.  Look
-to this file as an example of the format used for configuration files.
-.TP
-2. /etc/yoinkrc
-This is the system-wide configuration file.  Not available on Windows.
-.TP
-3. $HOME/.yoinkrc
-This is your own personal configuration file.
-.TP
-4. $YOINKRC
-This is an optional environment variable you can set to point to a configuration
-file.
-.PP
-Options that are passed as arguments take precedence over options loaded from
-the configuration file(s).  This mechanism is good for running the game with a
-temporary setting which you do not intend to retain.  Examples:
-.PP
+You have a certain level of control over the operation of \fByoink\fP
+through options passed as program arguments or given in config files.
+\fByoink\fP looks for config files in several locations and in this order:

 .TP
 .TP

-yoink fullscreen=true
-Run Yoink with the option
-.I fullscreen
-as true.  This will run the game in full-screen mode.
+1. \fI@DATADIR@/yoinkrc\fP
+This is the base config file which should be considered read-only.  Look to
+this file as an example of the format used for config files.

 .TP
 .TP

-yoink maxfps=60
-Run Yoink with the option
-.I maxfps
-as 60.  This will cap the display rate at 60Hz.
-.PP
-You can also set options with array values.  Arrays can be passed on the command
-line by surrounding all the parts with curly brackets and separating each part
-by a comma.  You may also have to quote the brackets so your shell doesn't parse
-them.  For example:
-.TP
-yoink videomode=\\{1024,768\\}
-Run Yoink with the top
-.I videomode
-as the numbers 1024 and 768.  The video size will be 1024x768.
+2. \fI/etc/yoinkrc\fP
+This is the system-wide config file.
+.TP
+3. \fI$HOME/.yoinkrc\fP
+This is your own personal config file.
+.TP
+4. \fI$YOINKRC\fP
+This is an optional environment variable you can set to the path of a
+config file at a non-standard location.  See the \fBENVIRONMENT\fP section
+below for more information.

 .PP
 .PP

-Here is a list of some of the options available:
+As usual, options that are passed as arguments take precedence over options
+loaded from any config file.  Here is a list of some of the options
+available at your disposal:

 .TP
 .B detail
 .TP
 .B detail

-The level of detail.  Possible values are high, medium, and low.  This effects
-the number of objects drawn to the screen.  A high level of detail will draw
-everything but could cause poor frame rates if the graphics driver can't keep up
-with the load.  Lower levels will omit certain details which aren't crucial for
-playing the game with the benefit of higher frame rates.  See the Notes for more
-ways to get good performance.
+The level of detail.  Possible values are 1, 2, or 3 where 1 means the
+least amount of detail and 3 means the most.  This effects the number of
+objects drawn to the screen.  A high level of detail will draw everything
+but could cause poor frame rates if the graphics driver can't keep up with
+the load.  Lower levels will omit certain details which aren't crucial for
+playing the game with the possible benefit of higher frame rates.  See the
+Notes for more ways to increase the game's performance.  The default value
+is 3.

 .TP
 .B doublebuffer
 .TP
 .B doublebuffer

-If true, double-buffering will be used to render animations with minimal
-distortions.  Otherwise, a single buffer will be used.  The recommended value is
-true.
+If true, double-buffering will be used to help minimize distortion and
+artifacts caused by the animation of the game.  Otherwise, a single buffer
+will be used.  The default value is true.

 .TP
 .B fullscreen
 .TP
 .B fullscreen

-If true, the window will capture the display and render the game in full screen
-splendor.  A value of false means the game will run in a window.
+If true, the window will capture the display and render the game in full
+screen splendor.  A value of false means the game will run in a window.
+The default value is false.

 .TP
 .B maxfps
 .TP
 .B maxfps

-The maximum number of frames to be drawn per second.  A value of 50 is pretty
-good.  If your computer is pretty old, can get away with decreasing this value
-and still have reasonably smooth animation.  You can set this to a very high
-number to effectively render as many frames as is possible, but the actual rate
-could be limited by vertical display synchronization, depending on the X11
-driver and settings used.  You should not set this option higher than the point
-where the vertical synchronization effectively limits the draw rate or else the
-game may not be able to update the physics on schedule which could actually
-significantly lower the quality of the animation.
+The maximum number of frames to be drawn per second.  If your computer is
+really old, you can get away with decreasing this value and still have
+reasonably smooth animation.  You can set this to a very high number to
+effectively render as many frames as is possible, but the actual rate could
+be limited by vertical display synchronization, depending on the X11 driver
+and settings used.  You should not set this option higher than the point
+where the vertical synchronization effectively limits the draw rate or else
+the game may not be able to update the physics on schedule which could
+actually significantly lower the quality of the animation.  The default
+value is 40.

 .TP
 .B printfps
 .TP
 .B printfps

-If true, the current number of frames being draw per second will be printed to
-the console.  This is usually off by default, but you can set this to true if
-you're interested in the draw rate you're actually getting.
+If true, the current number of frames being drawn per second will be
+printed to the console.  The default value is false.

 .TP
 .B resizable
 .TP
 .B resizable

-If true, the window will be resizable by the window manager.  This option is
-meaningless if the game is drawing to the full screen.
-.TP
-.B showcursor
-This option effects the visibility of the cursor while it is "hovering" over the
-window.  If the value is true, the cursor will be visible.  Otherwise, the
-cursor will be hidden.
+If true, the window will be resizable by the window manager.  This option
+is meaningless if the game is drawing to the full screen.  The default
+option is true.

 .TP
 .B timestep
 .TP
 .B timestep

-The amount of time in seconds between each update of the physics state.  A value
-of 0.01 or lower is ideal for accurate physics approximations.  Values that are
-much higher cause the CPU to do less work, but accuracy will suffer.  Errors
-could be introduced in the game with extremely high values.
+The number of times per second the simulation state will be updated.  A
+value of 100 or higher is ideal for a better physical simulation.  Values
+that are much lower cause the CPU to do less work, but accuracy will
+suffer.  Errors could be introduced in the game with extremely low values.
+The default value is 80.

 .TP
 .B videomode
 .TP
 .B videomode

-The resolution or size of the window.  The value is an array with three number
-elements representing the width, height, and bits per pixel that make up the
-video mode.  A typical value is {800,600} for a size of 800x600 pixels with
-millions of colors (the third number is optional).
-.PP
-This is only a list of the more useful options.  You'll have to use the source
-to find out about the more esoteric options, but you probably won't need to.
-.br
+The resolution or size of the window.  The value is an array with three
+number elements representing the width, height, and bits per pixel that
+make up the video mode.  The third number is optional.  The default value
+is {800,600}.  If passing on the command-line, you may need to escape the
+curly braces so the shell doesn't parse them.
+.PP
+This is only a list of the more useful options.  You'll have to use the
+source to find out about the more esoteric options, but you probably won't
+need to.
+.SH EXAMPLES
+Here are some examples of typical usage:
+.TP
+$ yoink maxfps=60
+Cap the allowable frame-rate to 60Hz.
+.TP
+$ yoink fullscreen=true
+Run \fByoink\fP in full-screen mode.
+.TP
+$ yoink videomode=\\{1024,768\\}
+Run \fByoink\fP with a resolution of 1024x768.  Notice the escapes for the
+curly braces so the shell doesn't parse them.

 .SH ENVIRONMENT
 .SH ENVIRONMENT

-.PP
-.B yoink
-responds to some variables in the environment:
+\fByoink\fP responds to some variables in the environment:

 .TP
 .TP

-HOME
+.I HOME

 If set to a path of a valid directory (presumably a user's home directory),
 If set to a path of a valid directory (presumably a user's home directory),

-.B yoink
-will look for a file at
-.I $HOME/.yoinkrc
-and load it as a configuration file.  Saving options within the game will cause
-this file to be over-written with the new options, unless the
+\fByoink\fP will look for a file at \fI$HOME/.yoinkrc\fP and load it as a
+config file.
+.TP
+.I USER
+\fByoink\fP uses this variable to guess the user's nickname, for a high
+score entry or whatever.
+.TP
+.I YOINK_DATADIR
+If set to a path of a valid directory, \fByoink\fP will look in this
+directory first when it is loading game assets.  Set this variable if you
+move the game's assets to another directory or perhaps want to load your
+own custom assets rather than the defaults.
+.TP

 .I YOINKRC
 .I YOINKRC

-variable is set.
-.TP
-USER
-.B yoink
-uses this variable to guess the user's nickname, for a high score entry or
-whatever.
-.TP
-YOINK_DATADIR
-If set to a path of a valid directory, 
-.B yoink
-will look in this directory first when it is loading game assets.  Set this
-variable if you move the game's assets to another directory or perhaps want to
-load your own custom assets rather than the defaults.
-.TP
-YOINKRC
-If set to a path of a valid configuration file, 
-.B yoink
-will load the options from that file, and those options will take precedence
-over options loaded from other configuration files.
-.br
+If set to a path of a valid config file, \fByoink\fP will load the options
+from that file, and those options will take precedence over options loaded
+from other config files.

 .SH NOTES
 .SH NOTES

-.PP
-Yoink may or may not be playable with acceptable frame rates without a hardware
-accelerated OpenGL driver installed and working, depending on how fast your CPU
-is.  Yoink is really not all that heavy on graphics, but it doesn't take much to
-overload a software implementation.  If you're stuck without hardware
-acceleration, there are some things you can do to get better frame rates:
+\fByoink\fP may or may not be playable with acceptable frame rates without
+a hardware accelerated GL driver installed and working, depending on how
+fast your CPU is.  \fByoink\fP is really not all that heavy on graphics,
+but it doesn't take much to overload a software implementation.  You should
+first check the documentation provided by your OS provider to see how to
+enable direct rendering.  If you're really stuck without hardware
+acceleration, there are some things you can do to get marginally better
+frame rates:

 .TP
 1. Decrease the resolution.
 .TP
 1. Decrease the resolution.

-Use the
-.I videomode
-option.  This speeds up software renderers considerably.
+Use the \fBvideomode\fP option or just resize the window if the
+\fBfullscreen\fP option is false and the \fBresizable\fP option is true.
+This can speed up a software renderer considerably.

 .TP
 2. Decrease the level of rendering detail.
 .TP
 2. Decrease the level of rendering detail.

-Use the
-.I detail
-option.  The game world may look sparse or incomplete, but that may be better
-than choppy animation.
-.PP
-On the other hand, if you already get high frame rates, you may also want to cap
-the rate so that your computer doesn't do more work than it really needs to.
-You can get reasonably smooth animation at around 30fps, but you can probably
-tell a difference between that and a higher rate like 50fps.  The latter will
-look noticeably smoother and nice, while the former is just "okay."  See
-the
-.I maxfps
-option.
-.br
+Use the \fBdetail\fP option.  The game world may look sparse or incomplete,
+but that's probably better than choppy animation.
+.TP
+3. Decrease the timestep.
+You can set the \fBtimestep\fP to be as low as the your \fBmaxfps\fP
+option.  Remember the trade-off here is decreased simulation accuracy.

 .SH BUGS
 .SH BUGS

-.PP
+.IP \(bu 3
+The robots are currently lacking in intelligence.
+.IP \(bu

 Although the pixelated graphics are intentional, there are some unintended
 Although the pixelated graphics are intentional, there are some unintended

-artifacts which are more obvious on certain OpenGL implementations.
+artifacts which are more obvious with certain video drivers.

 .PP
 Send bug reports, patches, and love notes to:
 .PP
 Send bug reports, patches, and love notes to:

-.br
+.IP

 Charles McGarvey <@PACKAGE_BUGREPORT@>
 .SH AUTHOR
 .PP
 Neil Carter was the original creator of Yoink, his winning entry in the
 Charles McGarvey <@PACKAGE_BUGREPORT@>
 .SH AUTHOR
 .PP
 Neil Carter was the original creator of Yoink, his winning entry in the

-uDevGames 2003 Mac game development contest.  Charles McGarvey restored the game
-and is the current maintainer.
+uDevGames 2003 Mac game development contest.  Charles McGarvey restored the
+game and is the current maintainer.