      ______              ___________________              ______
      >     |____________|  AstroMail 1.01   |____________|     <
      ~~||~~|  Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~
        ||   ~~~~~~~~~~~~                     ~~~~~~~~~~~~   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                     CENTURION                     ||
        ||                                                   ||
        ||                                                   ||
        ||                        -*-                        ||
        ||                                                   ||
        ||                                                   ||
        ||                   AstroMail 1.01                  ||
        ||                                                   ||
        ||       A Netmail Interface for AstroWar 1.00       ||
        ||                                                   ||
        ||          Copyright (C) Damian Walker 1997         ||
        ||                                                   ||
        ||                                                   ||
        ||                        -*-                        ||
        ||                                                   ||
        ||                                                   ||
        ||                    USER MANUAL                    ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                  .   |                            ||
        ||                     \|/    *     +                ||
        ||                    --+--                          ||
        ||               +     /|\            .              ||
        ||                      |    .  +                    ||
        ||                  *   |          *                 ||
        ||                        ().                        ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||   ____________                     ____________   ||
      __||__|  Copyright |___________________|    1997    |__||__
      >     |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~|     <
      ~~~~~~              ~~~~~~~~~~~~~~~~~~~              ~~~~~~
.hAstroMail 1.01 - User Manual
.fContents                                                               %2d
        AstroWar 1.01 - Fidonet Netmail Interface for AstroWar 1.00

        Copyright (C) Damian Walker 1997

        This program is free software; you can redistribute it and/or
        modify it under the terms of the GNU General Public License as
        published by the Free Software Foundation; either version 2 of
        the License, or (at your option) any later version.

        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public
        License along with this program; if not, write to the Free
        Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
        MA 02111-1307, USA.

SECTION 0_______________________________________________________________
                                                                Contents

        1.      INTRODUCTION
        1.1.    An Explanation of AstroMail
        1.2.    Software Requirements
        1.3.    Acknowledgements
        1.4.    Update History

        2.      INSTALLING AND RUNNING
        2.1.    Unpacking the Archive
        2.2.    Setting Up AstroMail
        2.3.    Using AstroMail in your AstroWar Games

        3.      PLAYING ASTROWAR VIA THE ASTROMAIL INTERFACE
        3.1.    Getting Started
        3.2.    Scouting, Conquering and Redeployment
        3.3.    Requesting Details About Your Empire
        3.4.    The Message System
        3.5.    Winning the Game
        3.6.    Resigning Your Position

        4.      RECOMPILING THE ASTROMAIL SOURCE CODE

        5.      TROUBLESHOOTING
        5.1.    Cannot open log file <filename>
        5.2.    Command line error: type 'astroml ?' for help
        5.3.    AstroMail already running
        5.4.    Out of memory <action>
        5.5.    Bad return code <number> from <technobabble>
        5.6.    Bad command in line <number> of <path>astroml.data
        5.7.    Cannot read config file <filename>
        5.8.    Cannot open detail file <filename>
        5.9.    Bad command in detail file <filename>
        5.10.   Cannot open game list <filename>
        5.11.   Bad detail file (line <line> in <gamelistfile>)
        5.12.   Bad line <line> in game list <file>
        5.13.   Game list <filename> is empty
        5.14.   Cannot open file <filename>
        5.15.   Bad header in file <filename>
        5.16.   Cannot create file <filename>

        A.      GENERAL REFERENCE
        A.1.    The AstroMail Command Line
        A.2.    Configuration File Commands

        B.      BINARY FILE FORMATS
        B.1.    The User File
        B.2.    The Player File
        B.3.    The Join Request Queue
        B.4.    The Player Fleet File

        C.      SUPPORT AND RESOURCES FOR ASTROWAR AND RELATED PROGRAMS
        C.1.    Resources on the Internet
        C.2.    Resources in Fidonet
        C.3.    Contacting the Authors
.fIntroduction                                                        %2d
SECTION 1_______________________________________________________________
                                                            Introduction

        This section introduces you to AstroMail, the Fidonet netmail
        interface to the AstroWar play-by-mail game.  Section 3 is a
        player guide.  Feel free to extract section 3 from this manual
        to provide your players with an explanation of how to play the
        game.

        -Other FTN Networks---------------------------------------------
         Often in this manual you will see reference to 'Fidonet' users,
         and 'Fidonet' software.  These terms apply to any network which
          uses Fidonet technology; AstroMail isn't restricted to Fidonet
                                                                 itself.
        ----------------------------------------------------------------

1.1.    An Explanation of AstroMail

        AstroMail is a mail server for Fidonet netmail, allowing Fidonet
        users to play the AstroWar play-by-mail game.  Before going
        further with AstroMail, it is necessary to have an understanding
        of AstroWar itself.  AstroMail is useless without AstroWar,
        anyway.

        AstroWar, to remind you, is a game of space conquest, intended
        to be played by mail.  It doesn't have any interface of its own,
        and it just reads orders and writes reports to a pair of binary
        files to which the players do not even have access, let alone
        understanding.

        AstroMail takes orders from players in the form of text commands
        in the body of Fidonet netmail message, and saves them as binary
        records in AstroWar's orders file, ready for AstroWar to
        process.  Similarly, it takes binary reports from AstroWar's
        report file after turn processing, and sends these reports to
        players in the form of text paragraphs, tables and ASCII map
        images, in the body of a Fidonet netmail message.

        Apart from the player guide, AstroWar itself will not be
        described further here.  You should have a copy of AstroWar, and
        AstroWar's manual has all the information you need to know about
        the game host.  Details about how to get hold of AstroWar are
        available in Appendix C.

1.2.    Software Requirements

        You obviously need an AstroMail executable before you can run
        the program, so if you only have the source code distribution,
        you must follow the instructions in section 4, 'Recompiling the
        AstroMail Source Code'.  Alternatively, you may find that there
        is already a binary distribution for your platform, which will
        contain the executable.

        In addition to AstroMail itself, you will need a copy of
        AstroWar, the game host.  AstroMail does not process orders or
        generate game reports, it only acts as a translator between the
        AstroWar game host and Fidonet users.  Refer to Appendix C for
        details of resources.

        Finally, AstroMail is useless without a Fidonet mailer, mail
        reader and processor of some sort.  Both the mail reader and the
        mail processor must support a '*.MSG' type message area for
        netmail; *.MSG is the closest thing Fidonet has to a portable
        standard for storing mail.

        -Games Run Locally----------------------------------------------
            If you are only interested in using AstroMail to play a game
            locally, you can get by without the mail processor, you only
        need the mail processor and mailer are only required if you wish
           to allow your AstroWar games to be accessed by users of other
                                          Fidonet point or node systems.
        ----------------------------------------------------------------

        If you don't have the Fidonet software you need, then the
        ever-handy Appendix C gives some tips about where to start
        looking for it.

1.3.    Acknowledgements

        A number of people have helped in the development of AstroMail.
        First of all, there are the developers.  Apart from myself, they
        are Tim Franklin and Ricky Walker, who helped with development
        of the Linux version, and Thomas Newsom, who is working on an
        Amiga version.

        There are also the beta testers of the DOS DPMI version.  These
        are Martyn Wilkins and Sy Hughes.

1.4.    Update History

        AstroMail 1.00
        - Initial release for DOS DPMI 386 and Linux

        AstroMail 1.01
        - Probably the quickest bug fix in history
        - Fixed Segmentation Fault bug in 'astroml in'
        - Tidied up one or other two minor nasties
.fInstalling and Running                                              %2d
SECTION 2_______________________________________________________________
                                                  Installing and Running

        This section gives details of installing the software, and using
        it to provide an interface to a regularly-run AstroWar game.
        Instructions are in tutorial form.

2.1.    Unpacking the Archive

        It is intended that the binary distribution of AstroMail be
        unpacked into the same directory that you unpacked AstroWar.
        Apart from the 'file_id.diz' and 'read.me' files, there are no
        filename clashes that you need to worry about.  AstroWar expects
        its configuration files to be in the same directory as the
        AstroWar configuration files it needs to access.

        -Running AstroMail under MS-DOS---------------------------------
                 Throughout this manual you will see long filenames like
            'astromail.data' and 'user.index'.  Don't worry about these,
           MS-DOS will truncate them internally to fit in the normal 8+3
                    pattern. Similarly, forward slashes in pathnames are
                                automatically translated to backslashes.
        ----------------------------------------------------------------

        When you have unpacked the binary distribution archive, you
        should see the following files in addition to the AstroWar files
        which were already there:

                astroml         or astroml.exe, the executable
                astroml.doc     this manual
                read.me         platform-specific details
                file_id.diz     the archive description
                astroml.sam     a sample configuration file

        If any of these files are missing, you can find them in one of
        the official binary distributions.  The only files which are
        really necessary, however, are the manual executable.

2.2.    Setting up AstroMail

        AstroMail automatically looks for game information in AstroWar's
        configuration files, so the only file you need to think about
        for AstroMail is its own configuration file.  This file contains
        settings to do with netmail.

        If you have the sample configuration file, you will see that it
        has a number of comments to help you.  The first command you
        will need is the 'name' command, which has the format:

                name <username>

        This sets the name that AstroMail will answer to.  By default it
        is 'AstroWar', so users playing your games will address their
        messages to 'AstroWar'.  You can change this if you like, but it
        is not recommended.

        The second thing you need to tell AstroMail is the directory in
        which your *.MSG-type message files reside, using the 'netmail'
        command:

                netmail <netdir>

        -Trailing Slashes-----------------------------------------------
         In just about every pathname you give to AstroWar or AstroMail,
              you must give a trailing slash, backslash or whatever your
            operating system uses as a directory separator.  THE NETMAIL
          PATH IS AN EXCEPTION.  Specify the netmail directory without a
                                           trailing directory separator.
        ----------------------------------------------------------------

        The directory <netdir> should be the same directory that you
        have used for netmail in the configuration of your mailer, mail
        processor and message editor.

        The 'logfile' command specifies where AstroMail should write log
        entries, and its format is:

                logfile <filename>

        Since AstroMail and AstroWar cannot be run concurrently, you can
        keep both programs' log entries in the same file if you like.
        That way, all AstroWar-related activities are in chronological
        order, which is handy for tracking down problems.

        In some areas of the world, routed Fidonet netmail is not
        supported.  In others, it is, but automatically-generated mail
        from robots such as AstroMail is unwelcome.  AstroMail has a
        facility to get round this honourably, by allowing you to send
        netmail directly to its destination.  Using one of the two
        commands 'routed' or 'direct', which take no parameters, you can
        set the default method for sending netmail to new players.
        Players can, however, modify the settings for their own mail
        individually once they are registered in AstroMail's user file.

        Futher control is given over the routing of netmail.  For both
        routed and direct players, you can set the exact attributes
        which will be used for outgoing messages of that type.  In
        particular, this gives you the choice of whether you will
        crashmail outgoing direct mail (i.e. call its destination), or
        put it on hold for the players to pick up (a more economical
        solution from your point of view).  The command which allows you
        to do this is 'attr', which takes the following formats:

                attr routed <flags>
                attr direct <flags>

        It is recommended that you include both an 'attr routed' and an
        'attr direct' command in your configuration file.  The <flags>
        are one or more of the following:

                cra     for 'crash'
                att     for 'file attach'
                hld     for 'hold'
                frq     for 'file request'
                upd     for 'update request'
                kil     for 'kill when sent'
                pvt     for 'private'
                loc     for 'local'
                dir     for 'direct'
                era     for 'erase file when sent'
                rcv     for 'received'
                snt     for 'sent'

        -A note about attributes----------------------------------------
        A number of the attributes available to you are useless, and not
            recommended for use with AstroMail.  These are 'att', 'frq',
          'upd', 'era', 'rcv' and 'snt'.  Others are highly recommended,
          like 'pvt' and 'loc'.  Refer to your Fidonet software's manual
                                           for details of what flags do.
        ----------------------------------------------------------------

        I recommend the flags 'pvt loc' for routed netmail, and 'pvt loc
        hld' for direct netmail.  Adding 'kil' to these attributes will
        ensure that the messages are not retained at your system once
        they have been sent.

        The final detail you need to supply to AstroMail is your Fidonet
        address.  Since I am the sysop of 2:2502/666.0, I doubt very
        much whether the default address in the sample file will be
        appropriate for your system.  You need to specify a full '4D'
        address here, so '2:2502/666' would not suffice, for instance.
        If you are not intending to connect to a bona fide Fidonet type
        network, you can keep the default address, or make up a nonsense
        address like '999:888/777.666'.

        If you take part in multiple networks, or you have more than one
        address on one network, you can include extra 'address' commands
        in your configuration file.  The LAST address in the
        configuration file is taken as a default address to use in
        outgoing messages.

2.3.    Using AstroMail in your AstroWar Games

        In order to integrate AstroMail into your AstroWar system, you
        need to have AstroMail do two things each turn.  Before you
        process your AstroWar turn using 'astrowar turn', you need to
        run 'astroml in' to import the mailed orders into AstroWar's
        binary orders file.  The format of this command is simply

                astroml in

        which will read orders into the orders file for any game listed
        in AstroWar's game list file.  It also does the following:

        * replies to any player trying to join or look at a non-existent
          game, by sending them a full game list via netmail,

        * catches some of the more obvious errors in orders, such as
          misspelled order commands or missing parameters, and replies
          with appropriate error messages,

        * allows players to modify their routed/direct setting and
          replies to such changes with a short confirmation message,

        * receives requests for information on a game and replies to the
          player with brief details extracted from the appropriate
          game's detail file.

        After a successful run of AstroMail, any incoming messages
        containing orders will have been processed and marked as
        'received'; you can have your software delete 'received'
        messages or move them into a special received netmail area, as
        you wish.  If you leave them where they are, AstroMail will
        notice the 'received' status of the message next time it is run,
        and skip the message.  However, leaving lots of old inbound
        messages in your netmail directory will eventually slow down
        AstroMail and any other netmail robot you run.

        This is only the first half of the job.  After you have run
        AstroWar to process a game, you must run AstroMail again to
        extract the resulting reports from the report file, and send
        them to the players.  This is done with 'astroml out', as
        follows:

                astroml out -game <gamename>

        where <gamename> is the name of the game you have just
        processed.  Note that the 'report.data' is not deleted
        afterwards, as you may well have other interfaces or utilites
        which want to look at the report file after AstroMail has
        finished with it.  Or you may want to back it up, in case of
        mis-haps.

        It is most convenient to run your AstroWar game using a batch
        file or script, since there are invariably a number of commands
        you need to run to process a turn.  This example is taken from
        the AstroWar manual:

                rm /astrowar/game1/report.data
                astroml in
                astrowar turn -game Game1
                astroml out -game Game1
                rm /astrowar/game1/orders.data

        The forward slashes and the use of 'rm' show this as a Unix
        script, but the general idea is relevant to AmigaDos scripts and
        MS-DOS batch files.  The 'rm' commands are explained in the
        AstroWar manual, but what we're interested in is the interaction
        between 'astroml in', 'astrowar turn' and 'astroml out'.

        Notice that there is no '-game' parameter on 'astroml in'.  This
        is because we don't know beforehand what games people have
        written orders for.  Rather than forcing you to run 'astroml in'
        separately for each game, a single 'astroml in' will process
        orders for any game.

        -Immediate message processing-----------------------------------
         If you are running a Fidonet node, you may want to run 'astroml
           in' after each inbound mail delivery.  This obviously doesn't
          affect the timing of 'astrowar turn', but it does help to keep
                        your netmail directory clear for other messages.
        ----------------------------------------------------------------

        However, 'astroml out' requires a game parameter.  Why?  Well,
        your 'astroml out' command will invariably be run when you have
        processed a game, but you may to process turns for different
        games at different times.  Since AstroMail cannot make any
        assumptions as to which games' report files are ready for
        sending out, you must specify a specific game to process when
        you run 'astroml out'.
.fPlaying AstroWar via the AstroMail Interface                        %2d
SECTION 3_______________________________________________________________
                            Playing AstroWar via the AstroMail Interface

        This player guide is based on the more general player guide
        included in the AstroWar manual.

3.1.    Getting Started

        AstroWar is a simple game of space conquest, usually played by
        email.  The simplicity of the rules mean that the time taken to
        learn the game is extremely short.  However, it may take just as
        long to develop a winning strategy as it does for more complex
        games.

        Let's take a look at the game rules before we go into details of
        how to play.  The map consists of a number of planets spread
        across a galactic map.  The number of planets and the size of
        the map are defined by the person running the game.

        There is only one type of planet, although each planet has a
        production rating.  This production rating reflects the number
        of ships that planet produces each turn, when it is owned by a
        player.  Neutral planets do not produce any ships.

        Ships are not treated individually in AstroWar.  There is only
        one type of ship, the variation being in the number of ships you
        send to the planets you are attacking.  Ships are sent in fleets
        of one or more ships, and each fleet's mission is decided by the
        number of ships sent, and the ownership of the planet the ships
        are being sent to.

        Part of the game's attraction lies in the high level of secrecy.
        In some games, you can see the entire map when you start the
        game, and sometimes you can see where other empires are.  Some
        games are very open, and allow you to see as much detail about
        other players' empires as those players can see.

        This is not the case with AstroWar.  When you start playing
        AstroWar, you only see full details of your homeworld, and the
        positions of nearby planets.  To get more information, you must
        scout the planets you can see, and you must start to expand
        before you see planets further away.

        But I'm getting ahead of myself here, for before any of this
        becomes apparent you must first join a game.  In order to join a
        game, you must submit a 'join' request.  With this join request
        you give a name which will be used to identify your empire.
        Your empire name can be up to 15 characters long.

        Upon successfully joining a game, you will receive confirmation
        that your request to join has been accepted.  With this you will
        be given the name of your homeworld, that homeworld's details,
        and a map of nearby planets to get you started.  Note that
        homeworld planets always have a production of 15 ships per turn.

        There are a few cases in which a join request might fail.
        Firstly, you might choose an empire name which is already in
        use.  This is unlikely, but possible.  Another case in which a
        request to join might be rejected is when the game is full, i.e.
        there are no planets which have not already been scouted or
        taken.  In the former case, just try to join again, with a
        different name.  In the latter case there's nothing you can do,
        except wait for the game to finish and re-start, or find another
        game.

        To address your join order, and other commands, to AstroMail,
        you send a netmail like the following:

        ================================================================
        From: <yourname>                Of:   <youraddr>
        To:   AstroWar                  At:   <server address>
        Subj: <gamename>
        ----------------------------------------------------------------
        <text in here>
        ================================================================

        Where <yourname> and <youraddr> are obvious, <server address> is
        the address of the server which hosts the game you want to play,
        and <gamename> is the name of the game you want to play.  To
        find out what games are available, use '?' or another nonsense
        value as the game name, and put any old rubbish in the message
        body.  When the server receives your message, it will send you
        back a list of games.

        A join order, as recognised by AstroMail, looks like the
        following:

                JOIN AS MyEmpire

        where MyEmpire is the empire name you want to use.  Providing
        that your join order is accepted, your initial report should
        look like this:

        ================================================================
        From: AstroMail 1.01
        Subj: Report for game "Game1"
        ----------------------------------------------------------------
        Your application to join game 'Game1' of AstroWar was
        successful.  Your empire name is 'MyEmpire' and your homeworld
        is 'Ozo'.  Your planets are:

        Name               position prodn      ships
        --------------------------------------------
        Ozo                 6,   15    15         30

        Map of planets around Ozo:

              |-1                          13
        ------+------------------------------
            22|..............................
            21|..............................
            20|..............................
            19|..........................Ma..
            18|Oi............................
            17|..........Ad..................
            16|..............................
            15|..Po..........Oz....Ap........
            14|........Io..........Va........
            13|..............................
            12|........................Ei....
            11|..............................
            10|..Rr..........................
             9|......Eu......................
             8|..............................

        Ad=Ade (4,17). Ap=Apada (9,15). Ei=Eisho (11,12). Eu=Eujid
        (2,9). Io=Iowev (3, 14). Ma=Marbrarsere (12,19). Oi=Oiza
        (-1,18). Oz=Ozo (6,15). Po=Poc (0,15). Rr=Rrel (0,10).
        Va=Vawiegowax (9,14).
        ================================================================

        The key underneath the map is provided because the abbreviated
        planet names on the map are not necessarily unambiguous.  When
        giving planet names in orders, you can't use these abbreviations
        either, so you need to know the full planet name.

        -Replying to AstroMail------------------------------------------
               When replying to AstroMail, make sure that the 'to' field
          contains 'AstroWar' or whatever the server is set up to answer
        to, NOT 'AstroMail 1.01' as used in the 'from' field of replies.
         This slightly confusing approach is necessary to avoid unwanted
                                      conversations between mail robots.
        ----------------------------------------------------------------

        It is a good idea to start keeping track of your maps, planets
        and fleets on paper or in a text file.  The information you get
        from AstroWar, while complete, is not really in a form suitable
        for playing.  As more maps and lists come down, the data as
        received will be disorganised-- it's up to you to organise it
        for your later reference.

        At any time before or after you join a game, you can request
        information on it from AstroMail.  Just include an INFO command
        in your message (no parameters), and AstroMail will reply with
        the details of the game named on the subject line.  This will be
        done as soon as AstroMail receives your message, you won't have
        to wait for the next turn to be processed.

        Some systems are set up to use routed netmail as default, and
        others are set up for direct netmail.  In either case, you can
        control how your own netmail is dealt with at the server using
        either the ROUTED or DIRECT command.  This covers mail in all
        games, not just the game on the subject line.

        -Where you can use ROUTED and DIRECT----------------------------
               The text of messages for non-existent games, as described
         earlier, is completely ignored by AstroMail.  Therefore, ROUTED
          and DIRECT commands need to be in the body of a netmail with a
        valid game name on the subject line, even though they affect all
                                                  games you are playing.
        ----------------------------------------------------------------

        Some sysops will not welcome routed messages to and from
        AstroMail passing through their system.  Before joining a game
        of AstroWar at another site, check with your sysop or uplink
        about routed netmail.  If in doubt, send your mail directly and
        use 'DIRECT' to ensure that replies are not routed.

3.2.    Scouting, Conquering and Redeployment

        The first thing you will want to do when you start a new game is
        scout one or more of the planets which were shown on your first
        map.  To scout a planet, simply send a single ship to it.  When
        the ship arrives, you will receive details about the production
        and ownership of that planet, along with the number of ships
        currently in orbit.  The scout ship will then turn around and
        begin the return journey.

        Once you have received details about some of the nearby planets,
        you should start making your attacks.  A fleet of 2 or more
        ships sent to a neutral or enemy planet consititutes and attack
        force.  Generally, you should send more ships than are already
        in orbit around a planet if you wish to take it.  However, you
        can send your attacks in two or more 'waves' if you don't have
        enough ships to take the planet straight away.  The first
        arrivals will reduce the enemy's numbers, so that the later
        fleets have an easier job of taking the planet.  If a fleet
        takes a planet, it is disbanded, and the ships take up orbit
        around the planet.

        You can start making attacks before you scout, but this is not
        always a good idea, particularly if you are joining a game which
        has already been running for a number of turns.  For all you
        know, an attack fleet sent out 'blind' might be travelling
        towards a planet belonging to a relatively powerful empire, and
        this is not a good way to gain allies.

        Once you have more than one planet, you may want to start
        redistributing your forces, for more effective attacks or
        defence.  Sending any number of ships from one of your planets
        to another is a normal fleet movement.  When the fleet arrives,
        it will be disbanded and the ships will join those in orbit
        around the planet.

        -A Note About Fleet Movements-----------------------------------
        A fleet does not start to move towards its destination until the
           turn after it is launched.  So, for instance, if you launch a
            fleet from one planet to a planet four squares away, it will
          still be four squares away on its first turn; only in the next
                                             turn will it start to move.
        ----------------------------------------------------------------

        To send a fleet using AstroMail, use the 'send' command, as
        shown below:

                SEND 10 SHIPS FROM Ozo TO Ade

        Capitalisation is unimportand, so 'send 10 sHIps from ozo to
        ADE' would also work.  SHIPS, FROM and TO are noise words which
        you can omit if you like, and SHIP is a suitable replacement for
        SHIPS.  There is a shorthand for sending scouting missions, an
        example of which is shown below:

                SCOUT Ade FROM Ozo

        where FROM is a noise word.  Notice that the order of origin and
        destination planets is reversed, to preserve grammar.

3.3.    Requesting Details About Your Empire

        Although the reports you receive from scouting, attacking and
        fleet movements tell you everything you need to know about your
        planets, there are times when you will want reminding about
        various aspects of your empire.  There are a couple of reports
        which you can request from AstroWar, whenever you need them.

        The planet list contains a list of all your planets, together
        with a remider of the planets' positions, their production
        ratings and the number of ships in orbit around them.  Only your
        own planets are included in this list; if you want up-to-date
        information about enemy or neutral planets you must scout them.

        -Turn Phases----------------------------------------------------
            There are four phases to each AstroWar turn: Fleet movement,
        Order processing, Ship production and Victory checking, executed
         in that order.  Bear this order in mind when submitting orders;
             for example, a planet report (a response to a 'planet list'
             order) will not take into account the ship production which
                                               comes later in that turn.
        ----------------------------------------------------------------

        The fleet list contains a list of all your fleets, with a
        reminder of their planets of origin and their destinations.  The
        list also contains the number of ships in the fleets, and their
        distances from their objectives.  You can use the distance
        figure to work out how long it will be before a fleet arrives.

        As your empire expands, you will want to be able to see more of
        the map.  This information isn't given to you automatically, you
        must request it using the map order.  When you submit a map
        order, you must give the name of a planet around which the map
        will be centred.  You can only centre a map around a planet you
        own, so in order to begin mapping the entire galaxy you must
        start expanding your empire.

        Using AstroMail, you request a planet list with the LIST PLANETS
        command, which has no parameters.  LIST is a noise word, so
        PLANETS on its own will do.  Similarly, a fleet list is obtained
        using LIST FLEETS or just FLEETS.

        A 'map' command as understood by AstroMail looks like this,
        where FROM is a noise word which can be omitted.

                MAP FROM Ade

3.4.    The Message System

        In order that you can communicate with other empires, to form
        alliances, make threats or gloat over victories, there is a
        message system which passes free-form messages between players.

        To write to another empire, simply submit a 'write' order, along
        with the name of the empire you wish to send to, and the text of
        the message.  Next turn, that empire will receive that message
        with the your empire name identified as the writer (in order
        that he or she can reply).

        It is also possible to write a general announcement to all
        empires.  This is not always a good idea.  Usually your empire
        will be unknown to others until they see your planets, or
        receive a message from you.  Secrecy itself may often be a
        useful weapon, but writing a message to all will immediately
        reveal your existence to everyone else in the game.  Later on in
        the game, if your empire becomes powerful, you could perhaps use
        this facility as a propaganda tool.

        Finally, it is also possible to write messages to the system,
        and receive messages from the system.  Although this has no use
        in the standard game, it is there as a way of communicating with
        add-ons.  Add-ons can scan for messages to the system and
        interpret their contents as extended orders to access features
        in that add-on.  Similarly, replies or information generated by
        add-ons will be addressed as coming from 'the system'.

        In order to send a message in AstroMail, use the WRITE command
        as follows:

                WRITE TO SomeEmpire
                This is my message
                <blank line>

        Where SomeEmpire is a valid empire name, or 'system', or 'all'.
        The following lines are the message, terminated by a blank line.
        This does mean that AstroMail has an extra limitation on
        messages you send-- they cannot contain blank lines.  Players
        using other interfaces can include blank lines in their messages
        to you, though.

3.5.    Winning the Game

        The standard victory conditions dictate that the empire who owns
        everybody else's homeworlds wins the game.  This is a change
        from the usual condition of conquering all of everyone else's
        planets, since that condition usually results in a tedious end
        game where the eventual victor has to mop up the remains of
        defeated empires.

        One problem is that enemy homeworlds are not identified.  You
        can assume that, in a normal game, all the homeworlds will have
        a production of 15 ships per turn.  However, not all planets
        with this production are homeworlds.  You just have to hunt out
        all the non-neutral planets with 15 production until you are
        awarded victory.

        When victory is awarded to a player, a report is sent out to
        everyone saying who the winner is.  However, the game must be
        manually stopped and restarted by the person running the game,
        so it is possible that a few turns may go by with the 'victory'
        message being sent out.

        It is quite possible that victory conditions in a game have been
        disabled, making it 'open-ended'.  This means that the game will
        continue indefinitely.

3.6.    Resigning Your Position

        Once your position has become unworkable, or you want to quit
        the game for some other reason like lack of time, there is a
        'resign' command you can use.  Resigning from a game will cause
        all your planets to revert to neutral status, and will make all
        in-transit fleets wink out of existence.

        If you are going to have to stop playing a game, it's polite to
        resign properly.  If you just let your fleets build up
        uselessly, it will get in the way of legitimate players and ruin
        their enjoyment of the game.

        A RESIGN command as understood by AstroMail is simply the word
        RESIGN on its own on a line.  AstroMail will reply by quoting
        this line and adding the confirmation 'you have now been removed
        from this game'.  You will receive no further response from
        AstroMail, though you are free to rejoin the game again with a
        new empire if you wish.
.fRecompiling the AstroMail Source Code                               %2d
SECTION 4_______________________________________________________________
                                   Recompiling the AstroMail Source Code

        There are a number of reasons why you might want to recompile
        the source code, rather than using an existing binary
        distribution of the game.  The most obvious reason is that a
        binary distribution might not be available for your platform. Or
        perhaps there is some incompatibility between the appropriate
        binary distribution and your particular system (I know, for
        instance, that my 386 binary distribution will have problems
        with some versions of QEMM).

        Another reason you might want to recompile the source is to
        include some improvement to the basic game which would be
        impossible, or inconvenient, as an external add-on.  In such
        cases you might like to modify AstroMail itself for changes to
        gameplay or interface.

        The source distribution comes with all the necessary tools to
        recompile AstroMail, apart from a C compiler and an
        implementation of 'make'.  If you have C and 'make', and the
        source distribution, you can compile AstroMail.

        Most of AstroMail is written ANSI C.  It uses the MsgLib
        external library for accessing Fidonet *.MSG messages, and
        MsgLib is provided in the source distribution.  MsgLib itself
        includes some non-ANSI code for accessing directories.  This
        code is developed from ideas discussed by Kernighan & Ritchie in
        their book 'The C Programming Language', 2nd edition on ANSI C,
        in which they admit that it is non-ANSI.  However, with minor
        variations it is easily ported.  Check your compiler manual on
        how to read directories if you encounter problems with the code
        supplied.

4.1.    Makefiles and Platform-dependent Definitions

        Once you have extracted the source code into a new directory,
        your first step is to select an appropriate makefile and
        'platform' header.  For users of supported platforms, selection
        of the makefile is simply a case of making a mental note of
        which makefile to use when running 'make'.  If there is no
        makefile for your platform, you will have to create one yourself
        using one of the existing makefiles as a pattern.

        You don't have to use 'make' at all.  Some compilers which have
        integrated development enviroments (GUI or otherwise) have their
        own way of managing large projects, and you might prefer to use
        that rather than 'make'.  But these examples assume you are
        using the standard command line 'make', so you'll have to
        translate the examples into something appropriate for your
        development system.

        After sorting out a makefile, selecting or creating a
        'platform' file is only slightly more involved.  But first, what
        is this 'platform' file I keep talking about?  Well, some
        developers support platform differences by using a multitude of
        '#if's in their source code, to selectively compile different
        sections of program depending on which platform you are using
        (determined by #defined macros).

        I don't like this approach, since it makes my source code messy
        and unreadable, and when you want to add support for a new
        platform you have to keep track of where these code segments
        are.  Keeping them all in one source file is one solution, but
        that tends to compromise the structure of your program.

        The solution I employ is a combination of makefiles and
        'platform' headers.  As well as having a makefile for each
        platform, there is also a 'platform.*' file.  For instance, the
        Linux files are 'makefile.lx' and 'platform.lx'.  All the
        system-specific definitions are kept in 'platform.*', which is
        included (using the filename 'platform.h') in just about every
        source file.  So, for instance, in 'platform.lx' there is a
        line:

                #define stricmp(a,b) strcasecmp(a,b)

        since GCC under Linux uses 'strcasecmp' instead of 'stricmp';
        this approach, in my opinion, is much better than putting '#if's
        for each case-insensitive comparison I make.  The platform file
        also includes definitions of the structures used by the 'dir.h'
        functions employed in the reading of directories.

        Before you can go on to compile AstroMail, you must create
        'platform.h' with the contents of the appropriate platform
        header.  In some operating systems, such as Unix, you can create
        'platform.h' as a symbolic link to the platform file you need.
        In less sophisticated operating systems, such as DOS, you need
        to copy or rename the appropriate platform.file as 'platform.h'.

        When creating a 'platform.h' for a new platform, use one of the
        existing ones as a pattern, as you did with the makefile.  If
        you need to create a new platform file, I'd be grateful if you
        would send it to me at one of the addresses shown in Appendix C,
        so it can be included in future source distributions. The
        platform header also includes the program's exact title and
        version number, using the macro 'PROGNAME'.  Choose an
        appropriate name for your AstroMail port, as it will appear in
        the log and on the screen when the program is run.

4.2.    Building the Executable

        With the correct makefile selected and the 'platform.h' file in
        place, you can proceed to build your executable.  Simply run
        'make' as in the following example:

                make -f makefile.lx

        replacing 'makefile.lx' with the makefile you have chosen for
        your platform.  Upon successful compilation, you will see a
        range of object files, and the final executable.  Once you're
        happy with the executable, you can delete the object files if
        you like.

4.3.    Compiling the Documentation

        The documentation for the program is in the file 'astroml.txt'.
        This is the 'source' for the document 'astroml.doc', and is
        supplied as such so that you can make any changes you need (see
        later) without having to worry about messing up page formatting.

        To compile the documentation, first you must compile the program
        'doc.c'.  This is a single-file project, so you can just invoke
        your compiler to compile the single file into an executable.
        It's in ANSI C, so you shouldn't have a problem with it.  Using
        GCC (any platform) the command line is:

                gcc doc.c -o doc

        which will create 'doc' or 'doc.exe'.  'Doc' is a public domain
        utility for formatting documents, written specifically so that I
        could distribute documentation for AstroMail and other programs
        in 'source' form, while being sure that people could compile the
        document on any platform.  Feel free to use and distribute
        'doc.c' in your own projects.

        With a compiled executable for 'doc', you can generate the
        repaginated documentation.  Run the following command:

                doc astroml.txt -o astroml.doc

        and you will get the repaginated documentation in
        'astroml.doc'.  When writing 'doc' source yourself, notice the
        format of the '.h' and '.f' commands for headers and footers,
        the inclusion of '^L' characters for forced page breaks.

        'Doc' also semi-intelligent when it comes to inserting its own
        page breaks.  A single-line title will never be separated from
        the following paragraph, and as long as a paragraph is not too
        big to fit on the page, it will not be broken.  So unlike other
        simple page formatters, you can write and edit documents without
        thinking or worrying about where the pagebreaks will fall (as
        long as you use the same paragraph and title format as I do,
        that is).

4.4.    Preparing a Binary Archive for Public Release

        AstroMail is distributed under the GNU GPL, and all the
        conditions for distributing your port, or alteration, of
        AstroMail are contained in the file 'COPYING', distributed with
        the source and binary archives.  Read it carefully before
        distributing your version of AstroMail.

        In addition to the conditions, I also have a number of
        suggestions which you might like to follow, in order to help
        you, and me, to keep the software consistent.  You don't have to
        follow them, as the only mandatory conditions are those in
        'copying', but it would be helpful if you did.

        If you have created a port of the standard package to a new
        platform, you might like to consider sending it to me so that it
        can be distributed as an 'official' version.  This means that
        you will be consulted if and when new versions are released, so
        that you can keep your port up to date.

        The official binary distributions all contain the files listed
        in section 2.  Whether your version of the software is intended
        to be 'official' or not, you might like to ensure that at least
        those files listed are included in your package.  That way,
        users following this manual will find everything they need.

        Apart from the executable and documentation you have just
        created, there are the sample files which are included in the
        source distribution.  You can just copy these across to your new
        binary package.

        A 'read.me' file for your version would be useful.  You can use
        an existing 'read.me' from an official binary distribution as a
        pattern if you like.  This 'read.me' file should contain details
        specific to your version or platform, such as hardware and
        software requirements and installation instructions.

        The 'file_id.diz' is a multi-line description of the package,
        and as with the 'read.me', you might like to use a 'file_id.diz'
        from an existing binary distribution as a pattern.  The
        'file_id.diz' description format is widely used in Fidonet for
        importing descriptions into BBS file lists, but it is appearing
        more and more in files at FTP and WWW sites as well.

        -A Note about 'read.me' and 'file_id.diz'-----------------------
              Please don't be tempted to just copy the 'read.me' and the
           'file_id.diz' out of an existing distribution, especially the
                source distribution.  The files with the source code are
           inappropriate for a binary distribution, and the files coming
         with other binary distributions will want at least their titles
                                                               changing.
        ----------------------------------------------------------------

4.5.    Source Code Changes and Filename Conventions

        When the source code needs alterations to run on your platform,
        try to restrict changes to the makefile and 'platform' file if
        possible.  Use '#defines' in the platform header to reflect
        differences in library functions ('stricmp', for instance). If
        some functions are missing from your compiler, add an extra
        source file with an implementation of the function in it, put a
        reference to that source file in the makefile, and put the
        function declaration in the platform header.

        There are advantages to this approach, particularly if you want
        to keep your version up to date with the official one.  If you
        make changes to the other source files, you will have to make
        that same change to the source files for each new version of
        AstroMail.  If there are a multitude of changes you will have
        quite a bit of work ahead of you.

        There may be a reason that you need to change the existing C
        source, though.  Perhaps I use a function which has no
        equivalent in your compiler, and some task needs doing in a
        completely different way using whatever functions your system
        offers.  Or maybe you're using a GUI, and find AstroMail's
        text-based output unsuitable.

        In these cases, when you change a source file, keep the original
        intact and save your altered source file under a different name.
        Then change your makefile to refer to the new source file
        instead of the old one.  This way, your new source can be
        included in the official source distribution alongside the
        standard source code.

        There is a standard filename convention I use in these cases.
        You'll notice that all the base filenames are six characters or
        less.  This leaves an extra two characters for variations on the
        standard source files, and I usually add something in the format
        '_<letter>' where <letter> identifies the port.  So, an
        alteration to 'scrlog.c' for Windows might be named
        'scrlog_w.c'.  The Windows makefile would refer to 'scrlog_w.c'
        instead of 'scrlog.c', although all the functions within the
        source file would retain their existing names.

        In addition, the following filename conventions are used for the
        official distributions of AstroMail:

                asm100.*                Source distribution
                asm100<letter>.*        Binary distribution

        Where <letter> is a letter identifying the binary distribution.
        It is the same as the <letter> used for any extra source files,
        as described a moment ago.
.fTroubleshooting                                                      %2d
SECTION 5_______________________________________________________________
                                                         Troubleshooting

        This section takes some errors which may appear in the log or on
        the screen, and provides some explanation as to why they might
        be given.

5.1.    Cannot open log file <filename>

        For some reason, Astrowar cannot open the log file for output.
        AstroMail will not run without a log file.  The most likely
        explanation for this is that you have mis-typed a directory
        name.

        Another explanation is that you are trying to share log files in
        a multitasking environment.  If this is the case, make sure that
        either (a) AstroMail has its own non-shared log-file, or (b) that
        AstroMail never runs concurrently with any program whose log file
        it shares.

5.2.    Command line error: type 'astroml ?' for help

        Obvious.  A list of valid commands is given when you follow the
        instruction.  Alternatively, a more complete command line guide
        is given in appendix A.

5.3.    AstroMail already running

        AstroMail shouldn't be run concurrently with itself, with
        AstroWar, or with anything else which uses its data files.  It
        protects against this happening using a semaphore file,
        'astrowar.sem', saved in the main AstroMail directory.

        If AstroMail is interrupted (or crashes) in such a way that it
        cannot exit gratefully, this file will be left in the AstroMail
        directory and must be deleted before AstroMail or AstroWar can
        be run again.

5.4.    Out of memory <action>

        AstroMail has run out of memory.  This is unlikely, since
        AstroMail is not a memory hog.  The names of all games are read
        into memory at once, so if you try and run a couple of million
        games at one AstroWar installation, you might come across this.

        Alternatively, this might come about because of incompatibility
        with some memory manager or swap system.  If this is the case,
        there's not much you can do about it, apart from use another
        memory manager, or see if you can find another distribution of
        the software for your platform (compiled with a different
        compiler).

5.5.    Bad return code <number> from <technobabble>

        This is one of those awful return codes you can do nothing
        about, and it means that I haven't done my job properly.  It
        shows that two parts of the program aren't matching up properly.
        If you see this, please send an exact copy of your log file to
        me, along with precise details of the AstroMail version you are
        using, and what platform you are running it on.

5.6.    Bad command in line <number> of <path>astroml.data

        Another obvious one.  You've made a typo in your configuration
        file, on the line indicated.  The sample configuration file
        'astroml.sam' contains comments showing the exact format of each
        configuration command; at the time of writing there's only one.
        You can also find a full explanation of all configuration
        commands from AstroMail's configuration file, in Appendix A of
        this manual.

5.7.    Cannot read config file <filename>

        The configuration file cannot be read.  If the configuration
        file is present, this could be a mis-typed pathname on the
        command line or in the ASTROWAR environment variable described
        in Appendix A.

5.8.    Cannot open detail file <filename>

        A detail file is not present.  If you know the file exists,
        check the pathname.

5.9.    Bad command in detail file <filename>

        Check all the commands in the named detail file.  Appendix A of
        the AstroWar manual gives information about the commands in this
        file.

5.10.   Cannot open game list <filename>

        Another self explanatory one.  Check that your game list file
        exists, and that the pathname shown is correct.

5.11.   Bad detail file (line <line> in <gamelistfile>)

        Similar to the error described in 5.9, but this one is
        encountered when reading the game list (as the game list is
        read, the detail file in each directory is checked).  Check the
        line <line> in your game list file, to see which detail file
        caused the error.  Then look at that detail file; refer to
        section 5.9 for more information on debugging detail files.

5.12.   Bad line <line> in game list <file>

        One of the lines in your game list is neither a comment nor an
        existing directory containing a 'detail.data' file.

5.13.   Game list <filename> is empty

        Running AstroMail without at least one game set up is a waste of
        time.  Ensure that you have at least one path in your game list
        file, and that the directory contains a 'detail.data'.

5.14.   Cannot open file <filename>

        One of AstroMail's data files cannot be opened.  This usually
        appears with 'report.data' as <filename>, when you attempt to
        run 'astroml out' on a game which hasn't been processed.

5.15.   Bad header in file <filename>

        Each of AstroMail's binary data files contains an eight byte
        header, which confirms the file type and version number.  This
        error occurs when the header is not as expected for a given
        file.

        The most obvious cause is file corruption.  Another possible
        cause is that you're running an earlier version of AstroMail than
        that which created the data files.  It is quite possible that in
        future releases of AstroMail, the structures of some data files
        will be changed, in which case earlier versions of AstroMail may
        not be able to read the data files created by later versions.

5.16.   Cannot create file <filename>

        A file error has occurred when trying to create one of
        AstroMail's data files.  Ensure that the directory exists, and
        that it is not read only.
.fAppendix A - General Reference                                      %2d
APPENDIX A______________________________________________________________
                                                       General Reference

        This appendix contains just about everything you need to know
        about AstroMail's command lines, and the configuration file.
        Information on the AstroWar files which AstroMail accesses are
        given in the AstroWar manual.

A.1.    The Command Line, Environment and Error Levels

        The format of the AstroMail command line is

                astroml <command> <switches>

        <command> can be one of the following:

                in              process inbound order messages
                out             create outbound report messages
                ?               which displays a brief help screen.

        and <switches> are one or more of the following:

                -game <name>    The game to be created ('out' only),
                -path <dir>     Path to the 'astrowar.data' and
                                'gamelist.data' files,
                -from <addr>    an override to the default system
                                address used in the 'from' field of
                                outgoing messages ('out' only).

        If you miss out '-path', AstroMail looks in the current directory
        for its data files.  Instead of using the '-path' switch to
        point AstroMail to data files elsewhere, you can use the
        'ASTROWAR' environment variable.

        -Specifying a Path Name-----------------------------------------
              When specifying a pathname using the '-path' switch or the
           'ASTROWAR' environment variable, make sure you put a trailing
         slash or backslash (or other directory separator) at the end of
                        the pathname, as your operating system requires.
        ----------------------------------------------------------------

        AstroMail returns one of a number of error levels when it exits.
        You can use these to determine whether a run was successful or
        not, and why it might have failed.  This is especially useful
        when you are running AstroMail automatically overnight, as you
        can trap errors and somehow bring them to your attention (by
        posting a message, for example).  The error levels are:

                0       everything went OK
                3       error accessing some file or other
                4       bad header encountered in a file
                5       a file to be created already exists
                7       possible corrupt file or index
                9       out of memory
                10      bad command encountered

A.2.    Configuration File Commands

        This part of the appendix shows the composition of AstroMail's
        ASCII configuration file 'astroml.data'.  A blank line, or any
        line starting with a semi-colon (;) is regarded as a comment.

            name <username>     The name which AstroWar answers to.
                                Users address their messages to this
                                name at your system.  This setting has
                                no effect on the 'from' name used in
                                outbound messages, which is kept
                                constant to prevent mail robot
                                conversations.

            netmail <dir>       The netmail directory, as set up in your
                                mailer, mail processor and editor.  This
                                directory name should not have a
                                trailing slash or other directory
                                separator character.

            logfile <filename>  The file to which AstroMail's log
                                entries will be written.  Log entries
                                are in the common 'FrontDoor' format,
                                like AstroMail's, so that Fidonet sysops
                                can integrate their logs if they want.

            direct              Specifies that mail for new users is
                                sent directly, as specified with the
                                'attr direct' command.

            routed              Specifies that mail for new users is
                                sent routed, as specified with the 'attr
                                routed' command.

            attr routed <f>     Specifies the flags which are used in
            attr direct <f>     routed and direct netmail replies.  <f>
                                consists of one or more of cra (crash),
                                att (attach), hld (hold), frq (freq),
                                upd (update request), kil (kill), pvt
                                (private), loc (local), dir (direct),
                                era (erase file when sent), rcv
                                (received) or snt (sent).  Some of these
                                flags are nonsensical when applied to
                                AstroMail.

            address <addr>...   Specifies one or more addresses which
                                identify your Fidonet system.  Multiple
                                addresses can be used on one line, (up
                                to 80 characters) and multiple address
                                commands can be used.
.fAppendix B - Binary File Formats                                    %2d
APPENDIX B______________________________________________________________
                                                     Binary File Formats

        There aren't many reasons why you would want to access
        AstroMail's files.  The only reason I can think of is to write a
        utility that allows players to migrate from one interface to
        another.

        Usually you would use the 'AstroMail API' to access these files,
        that is, those PD files in AstroMail's distribution which allow
        access to AstroMail's files . However, if you use another
        language and you haven't got a C compiler, you may need to write
        your own code to access AstroMail's data files.  Note that
        report.c, orders.c, detail.c and gamlst.c are part of the
        AstroWar API included for convenience; find out more about them
        and the files they access from the AstroWar manual.

        The examples given in this section use BASIC format record
        definitions, with a few BASIC code examples, since BASIC is the
        only mainstream language I know apart from C (unless you want to
        see some COBOL, that is).

        -A Note About Text Values---------------------------------------
          All text values in AstroMail's files are null-terminated.  You
                will have to make sure your program processes and writes
        null-terminated string values correctly.  The recommended course
        of action is to write an equivalent to the AstroMail API in your
            language, and have the 'set' and 'get' routines do the work.
        ----------------------------------------------------------------

B.1.    The User File

        The user file is named 'user.data', and its index files are
        named 'user1.index' and 'user2.index'.  All these files are
        situated in the AstroWar/AstroMail directory, not in the game
        directories.  The first eight bytes of 'user.data' are a header,
        'ASM10UF' followed by a NUL, or 0, byte.  The index files have
        the 8-byte null-terminated headers 'ASM10U1' and 'ASM10U2'
        respectively.  Their definitions are as follows:

                '
                ' **** Definition of records in user1.index ****
                '
                TYPE UserIndex1
                    RecPos  AS LONG ' position of record - 1
                    UserNum AS LONG
                END TYPE
                '
                ' **** Definition of records in user2.index ****
                '
                TYPE UserIndex2
                    RecPos  AS LONG ' position of record - 1
                    UName   AS STRING * 36
                END TYPE
                '
                ' **** Definition of records in user.data ****
                '
                TYPE UserRecord
                    Deleted AS STRING * 1  ' ASCII 1 = deleted
                    UserNum AS LONG        ' user number
                    UName   AS STRING * 36 ' user name
                    FdZone  AS INTEGER     ' four
                    FdNet   AS INTEGER     ' ... parts of ...
                    FDNode  AS INTEGER     ' ... 4d Fidonet ...
                    FDPoint AS INTEGER     ' ... address
                    Direct  AS STRING * 1  ' ASCII 1 = direct
                END TYPE

        A small section of BASIC code for reading a record follows.  It
        assumes that the user number index file (user1.index) is #1 and
        the data file is #3 (both opened as BINARY), and that the index
        file pointer points to the start of the next index record:

                DIM UIndex AS UserIndex
                DIM User AS UserRecord
                GET #1, , UIndex
                GET #2, UIndex.RecPos + 1, UserRecord

        Note that we add 1 to the UIndex.RecPos.  The first byte of the
        file is 0 in C, or 1 in BASIC.

B.2.    The Player File

        The player file is named 'player.data', and its index files are
        named 'player1.index' and 'player2.index'.  A copy of each of
        these files is situated in each game directory. The first eight
        bytes of 'player.data' are a header, 'ASM10PF' followed by a
        NUL, or 0, byte.  The index files have the 8-byte
        null-terminated headers 'ASM10P1' and 'ASM10P2' respectively.
        Their definitions are as follows:

                '
                ' **** Definition of records in player1.index ****
                '
                TYPE PlayerIndex1
                    RecPos  AS LONG ' position of record - 1
                    UserNum AS LONG
                END TYPE
                '
                ' **** Definition of records in player2.index ****
                '
                TYPE PlayerIndex2
                    RecPos  AS LONG ' position of record - 1
                    EName   AS STRING * 36
                END TYPE
                '
                ' **** Definition of records in player.data ****
                '
                TYPE PlayerRecord
                    Deleted AS STRING * 1  ' ASCII 1 = deleted
                    UserNum AS LONG        ' user number
                    EName   AS STRING * 36 ' empire name
                END TYPE

        UserNum corresponds to the same field in the user file, so full
        user details can be found by cross-referencing.  EName is the
        empire name which the player uses for that game, and corresponds
        to the empire name in AstroWar's 'empire.data' file, described
        in AstroWar's manual.  Code for reading this file is similar to
        that for reading the user file.

B.3.    The Join Request Queue

        The join request queue is named 'joinrq.data', and its index
        file is named 'joinrq.index'.  A copy of both of these files is
        situated in each game directory. The first eight bytes of
        'joinrq.data' are a header, 'ASM10JF' followed by a NUL, or 0,
        byte.  The index file has the 8-byte null-terminated header
        'ASM10J1'. Their definitions are as follows:

                '
                ' **** Definition of records in joinrq.index ****
                '
                TYPE JoinRqIndex1
                    RecPos  AS LONG ' position of record - 1
                    TransNo AS LONG
                END TYPE
                '
                ' **** Definition of records in joinrq.data ****
                '
                TYPE JoinRqRecord
                    Deleted AS STRING * 1  ' ASCII 1 = deleted
                    TransNo AS LONG        ' transaction number
                    UserNum AS LONG        ' user number
                    EName   AS STRING * 16 ' desired empire name
                END TYPE

        UserNum corresponds to the same field in the user file, so full
        user details can be found by cross-referencing.  EName is the
        empire name specified in a 'join' command, and TransNo is a
        unique transaction number identifying this join request (see the
        AstroWar manual to find out how a join queue works). Code for
        reading this file is similar to that for reading the user file.

B.4.    The Player Fleet File

        The player fleet file is named 'pfleet.data', and its index file
        is named 'pfleet.index'.  A copy of both of these files is
        situated in each game directory. The first eight bytes of
        'pfleet.data' are a header, 'ASM10FF' followed by a NUL, or 0,
        byte.  The index file has the 8-byte null-terminated header
        'ASM10F1'. Their definitions are as follows:

                '
                ' **** Definition of records in pfleet.index ****
                '
                TYPE PFleetIndex1
                    RecPos  AS LONG ' position of record - 1
                    FleetNo AS LONG
                END TYPE
                '
                ' **** Definition of records in pfleet.data ****
                '
                TYPE PFleetRecord
                    Deleted AS STRING * 1  ' ASCII 1 = deleted
                    Fleetno AS LONG        ' fleet number
                    UserNum AS LONG        ' user number (owner)
                    Ships   AS LONG        ' ships in fleet
                    Origin  AS STRING * 15 ' planet of origin
                    Dest    AS STRING * 16 ' destination planet
                END TYPE

        UserNum corresponds to the same field in the user file, and the
        FleetNo, Ships, Origin and Dest fields correspond to those same
        fields in AstroWar's fleets file described in the AstroWar
        manual.  This data is held by AstroMail to remind players of
        details of fleets mentioned in arrival, battle and intelligence
        reports; such details are not included in AstroWar's report
        file. Code for reading this file is similar to that for reading
        the user file.
.fAppendix C - Support and Resources                                  %2d
APPENDIX C______________________________________________________________
                 Support and Resources for AstroWar and Related Programs

        This section gives details about what help and resources are
        available for AstroWar in Fidonet and on the Internet.  I won't
        give too much in the way of site addresses, since these can
        change.  I'd rather just give a addresses for official support
        sites, and use those sites to provide up-to-date information
        about other resources.  Hopefully the main support sites will
        remain where they are.

C.1.    Resources on the Internet

        The main Internet resource for AstroWar is the AstroWar home
        page, at:

                http://www.bsnet.co.uk/net2502/centurion/astrowar.html

        Links to other AstroWar-related web sites, and file space, will
        be added to this web page.  You can also find an AstroWar entry
        at Greg Lindahl's PBM List home page, at

                http://www.pbm.com/~lindahl/pbm.html

        I will try and arrange for AstroWar to be hosted at an FTP site,
        possibly ftp.pbm.com and ftp.funet.fi. If you wish to discuss
        AstroWar in a newsgroup, the best place to try would be
        rec.games.pbm.  I read that group, and I can answer your queries
        in the newsgroup or email.

C.2.    Resources in Fidonet

        Since Centurion is a Fidonet system, not an Internet one, you
        will find that support is more reliable in Fidonet.  A text
        equivalent to the AstroWar home page is available via routed
        netmail or file request.  To receive the document via netmail,
        send a netmail to INFOMAIL at 2:2502/666 with ASTROWAR as the
        subject.  To request the document as a (ZIPped) file, request
        ASTROWAR (a magic name) from the same address.

        All official source and binary distributions are available via
        file request from Centurion.  The filenames can be found on the
        web page and in the ASTROWAR document just mentioned.

        Finally, a support echo exists for AstroWar.  Its tag is
        ASTROWAR_UK, and despite the _UK suffix, international
        participants are welcome.  The echo is available from my system,
        and may be carried on various national or continental backbones.
        Netmail me for details.

C.3.    Contacting the Authors

        You can contact me, Damian Walker, via Fidonet netmail, at
        2:2502/666.  If you're on the Internet, email me at:

                damian.walker@f666.n2502.z2.fidonet.org

        which will go through the Fidonet/Internet gateway.  I do have
        an Internet address, but that changes from time to time (my
        current address will expire mid '98).  My real Internet address
        will be available on the AstroWar homepage.

        You can contact Tom Newsom, the Amiga developer, at his Fidonet
        address of 2:2502/61, or the Internet equivalent:

                thomas.newsom@f61.n2502.z2.fidonet.org

        At the time of writing, only Amiga, DOS and Linux versions are
        under development, so I can only give DOS/Linux and Amiga
        developer details here.  Details of contacting other authors
        should be in the 'read.me' files of their binary distributions.

        -Final Note-----------------------------------------------------
        AstroWar is the result of many months of programming and design.
         I hope that people enjoy it, but I don't know unless they write
             to me.  Please, whether you like the program or not, get in
               touch at one of the addresses above and let me know.  All
                            comments, source code and ideas are welcome.
        ----------------------------------------------------------------
