--- /dev/null
+.\"
+.\" 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