X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=doc%2Fyoink.6.in;h=ec41deebeb4913b918a558727cdd2e27220f4910;hp=2432bd5de9d39abdcdaf847bd69e7759b89e2d6c;hb=e495074443d9fd7bc16137084cf9de3d031b75c4;hpb=ca0f7bdfba63140dca0bd20586d31980f3938eb2

diff --git a/doc/yoink.6.in b/doc/yoink.6.in
index 2432bd5..ec41dee 100644
--- a/doc/yoink.6.in
+++ b/doc/yoink.6.in
@@ -28,7 +28,7 @@
 .SH NAME
 Yoink \- An alien-smashing action game.
 .SH SYNOPSIS
-.B yoink [-h|--help] [OPTION=VALUE]...
+.B yoink [-h|--help] [-i|--info] [OPTION=VALUE]...
 .br
 .SH DESCRIPTION
 .PP
@@ -42,7 +42,10 @@ arcade games like Joust, Bombjack, Rampage, and Defender--simple, fast-moving
 action.  Basic arguments include:
 .TP
 .B -h, --help
-Display this help and exit.
+Display basic usage information, and exit immediately.
+.TP
+.B -i, --info
+Display build and environment details, and exit immediately.
 .br
 .SH TIPS
 .PP
@@ -67,118 +70,103 @@ around, especially in the sky, if you can't find the last few.
 .br
 .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.
+Options are set from config files and command-line arguments.  A
 .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.
+configfile ("yoinkrc") consists of key-value pairs.  They are loaded in this
+order:
 .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.
+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
 2. /etc/yoinkrc
-This is the system-wide configuration file.  Not available on Windows.
+This is the system-wide config file.  Not available on Windows.
 .TP
 3. $HOME/.yoinkrc
-This is your own personal configuration file.
+This is your own personal config 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:
+This is an optional environment variable you can set to the path of a config
+file at a non-standard location.
 .PP
-.TP
-yoink fullscreen=true
-Run Yoink with the option
-.I fullscreen
-as true.  This will run the game in full-screen mode.
-.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.
-.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 the config file(s).  Here is a list of some of the options available
+at your disposal:
 .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
-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
 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.
+splendor.  A value of false means the game will run in a window.  The default
+value is false.
 .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
-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
 If true, the window will be resizable by the window manager.  This option is
-meaningless if the game is drawing to the full screen.
+meaningless if the game is drawing to the full screen.  The default option is
+true.
 .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.
+display.  If the value is true, the cursor will be visible.  Otherwise, the
+cursor will be hidden.  The default value is true.
 .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
 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).
+video mode.  The third number is optional.  The default value is {800,600}.  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.
 .br
+.SH EXAMPLES
+.PP
+Here are some examples of typical usage:
+.PP
+.TP
+yoink fullscreen=true
+Run Yoink in full-screen mode.
+.TP
+yoink maxfps=60
+Cap the allowable frame-rate to 60Hz.
+.TP
+yoink videomode=\\{1024,768\\}
+Run yoink with a resultion of 1024x768.  Notice the escapes for the curly
+braces so the shell doesn't parse them.
 .SH ENVIRONMENT
 .PP
 .B yoink
@@ -189,10 +177,7 @@ 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
-.I YOINKRC
-variable is set.
+and load it as a config file.
 .TP
 USER
 .B yoink
@@ -207,10 +192,10 @@ 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, 
+If set to a path of a valid config file, 
 .B yoink
 will load the options from that file, and those options will take precedence
-over options loaded from other configuration files.
+over options loaded from other config files.
 .br
 .SH NOTES
 .PP
@@ -218,32 +203,41 @@ 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:
+acceleration, there are some things you can do to get better frame rates, in
+order of effectiveness:
 .TP
 1. Decrease the resolution.
 Use the
 .I videomode
-option.  This speeds up software renderers considerably.
+option or just resize the window if the
+.I fullscreen
+option is false and the
+.I resizable
+option is true.  This speeds up software renderers considerably.
+.TP
+2. Decrease the timestep.
+Use the
+.I timestep
+option.  You can set the timestep to be as low as the your
+.I maxfps
+option, but it is not recommended to set this lower than the target frame rate.
+Remember the trade-off here is decreased simulation accuracy.  Try to set your
+maxfps to 30Hz and your timestep to 60Hz:
+.PP
+yoink maxfps=30 timestep=60
 .TP
-2. Decrease the level of rendering detail.
+3. 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
 .SH BUGS
 .PP
 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
+The robots are not very bright.
 .PP
 Send bug reports, patches, and love notes to:
 .br