.\"
.\" Copyright (c) 2009-2011, Charles McGarvey
.\" All rights reserved.
.\" 
.\" Distributable under the terms and conditions of the 2-clause BSD
.\" license; see the file COPYING for a complete text of the license.
.\"
.Dd June 14, 2011
.Dt YOINK_README 7
.Os
.Sh NAME
.Nm yoink_readme
.Nd general information about yoink
.Sh DESCRIPTION
Yoink is a game created by Neil Carter for Mac OS.  You play the part of a
flying alien heroine who must defend her home on Earth from other airborne
alien invaders.
.Pp
This version of the game uses all new code and modern frameworks to bring
this simple, fast-moving action game to a wider audience.
.Ss INSTALLATION
Installing Yoink is simple.  You can typically use commands such as these:
.Pp
.D1 cd /path/to/yoink
.D1 ./configure
.D1 make && make install
.Pp
This will install Yoink into the
.Pa /usr/local
directory.  To run Yoink, issue the command:
.Pp
.D1 /usr/local/bin/yoink
.Pp
or just
.Nm yoink
if
.Pa /usr/local/bin
is already in your
.Ev PATH Ns .
See
.Xr yoink_install 7
for a more detailed discussion about the build system and a list of
required packages.
.Ss LICENSE
The new code is released under the 2-clause BSD license.  The old code and
original resources are provided under the zlib/libpng License.  See the
.Pa COPYING
file for complete details.  The full texts of applicable licenses can be
found in
.Pa doc/licenses
within the Yoink package.
.Ss ABOUT THE CODE
The code is a complete rewrite, containing none of the original code.  I've
made some effort to put the more generic or reusable code into a separate
library called libmoof.  I've also made an effort to incorporate 3rd-party
code that happened to fit well into what I needed.  So, generally, the
source code is separated into these three categories:
.Bl -enum
.It
Yoink-specific code.  This is the code in the
.Pa src
directory.  These classes reside in no explicit namespace.
.It
Reusable code.  The code is in
.Pa src/moof Ns ,
and it is compiled as a convenience library.  These classes and helper
functions reside in the moof namespace.  Since I wrote this code alongside
the Yoink-specific stuff, there is somewhat of a blurry line between the
two categories, unfortunately.
.It
Third-party code.  This is made up of free code from other projects or
libraries, the licenses of which are also noted in the
.Pa COPYING
file.  This code resides in various namespaces and in various
subdirectories of
.Pa src Ns .
.El
.Ss PACKAGING
Here are some tips to help packagers:
.Bl -bullet
.It
The build scripts are written in Lua, so make sure the Lua interpreter is
installed.  That shouldn't be a problem since Yoink depends on the Lua
library anyway.
.It
The
.Pa Makefile
will only work well with GNU make.  On some systems, this is installed as
.Nm gmake Ns .
.It
The
.Pa configure
script supports most of the useful options that an Autoconf-generated
script would have, and the
.Pa Makefile
supports
.Ar DESTDIR Ns .
.El
.Pp
See
.Xr yoink_install 7
for a more detailed discussion about the build system.
.Ss SENDING PATCHES
I'll gladly entertain patches if you want to help out.  Just email me your
stuff or tell me where to pull if you use git.  If you're interested in
that, please observe the following:
.Bl -bullet
.It
Stick to the coding style of the source code files you edit.  Follow the
general style of method and variable naming, as well as white space
formatting.  In particular, use literal tabs with an assumed tabstop of 4
characters.  Also, try to limit line lengths to 75 characters.
.It
For legal reasons, don't include other peoples' code with your patch.  You
must also agree to license your changes according to the same terms and
conditions as the files you edit, usually the 2-clause BSD license.
.It
If you want your name and contact information in the
.Pa AUTHORS
file, please make it so in the patch you provide.
.El
.Sh SEE ALSO
.Xr yoinkrc 5 Ns ,
.Xr yoink 6
.Sh AUTHORS
.Bl -tag -width 2i -compact
.It An Charles McGarvey
.Mt chaz@dogcows.com
.El