                --------------------------------
                              ALex
                          (Version 1.0)

                             Freeware
                          Copyright 1999
                         Stephen Griffiths
                --------------------------------


--------
Overview
--------

ALex is a utility program for writers using the ALAN interactive fiction 
authoring language. The ALAN WWW site is http://www.welcome.to/alan-if 

ALex - short for ALan gametext EXtracting program - is a 'text filter'
that searches a file of ALAN source code for text enclosed in double-quotes.
This is the text which will be visible to the player during gameplay. It
copies any such text found to a new file which can then be viewed or
spell-checked in a wordprocessor or text-editor program. (The ALAN source
code file is not touched or modified in any way.)

The aim of the program is to generate a text file which looks nicely
formatted in a word-processor and is easy to proof-read and spell-check.

By default, ALAN formatting control codes - like $p or $t - are automatically
replaced with the blank lines, tabs, etc that those codes represent. ALAN
parameter control codes - like $o or $2 - are replaced by capitalised text
like OBJECT or SECOND. (You can change these styles using options described
later in this file.)


--------------------
General Instructions
--------------------

ALex is a DOS commandline program. The program's behaviour can be controlled 
by specifying a variety of options on the commandline.

Setup
-----
Probably the easiest way to use the program would be to copy the file
alex.exe to the directory that contains your copy of the ALAN compiler -
alan.exe. Or you could copy alex.exe to the directory containing the
ALAN source code file you wish to scan.

Wherever you place alex.exe, its probably a good idea to place a copy of
this documentation file - alex.txt - in the same location.

Usage
-----
At a DOS commandline ensure your current directory is set to the one
containing your ALAN source code file. Then enter the command

    alex filename

where 'filename' is the name of your source code file. (You can leave off
the ".ala" extension as ALex will automatically append that if its
necessary.)

(Note that the MSDOS version of ALex only understands short DOS "8.3 format"
filenames. If your source-code files have long filenames you'll have to
specify the short format version of the filename to Alex. You can use the
DOS "dir /x" command to see the short filenames under Win9x/NT. For example,
your source code file might be called masterpiece.alan, dir /x may show that
the short name is master~1.ala so you should use the command "alex master~1"
to process masterpiece.alan with ALex.)

The ALex output will be saved in a file called <filename>.txt. If a file
called <filename>.txt already exists ALex will shut down. It will not
overwrite an existing file unless you ask it to. (The overwrite option
- "-OO" - is described later in this file.)

So, to process an ALAN file called 'example.ala' through ALex, type

    alex example

The output will be placed in a file called example.txt.


-------
OPTIONS
-------

You can change the behaviour of ALex by specifying various commandline
"switches".

For example, by default the output file lists the source code line number
for the start of each bit of text. If you don't want line numbers cluttering
up the output file, run ALex with the "no line-numbers" option by adding
-NL to your commandline, eg:

    alex filename -NL

Commandline switches or "parameters" can be written in capitals or lower
case.

Except for the input filename, each switch must begin with either - or /.
(Either symbol will do, in the DOS/Windows version, according to your
personal preference.)

Multiple switches can be specified and can be listed in any order. However
you can't join two or more switches into a "parameter string". For example,
the switches -NL and -OO cannot be written as -NLOO as they could be with
some other software packages.


Full option list
----------------
The full list of possible commandline parameters for this version of
ALex are:

alex -help <inputfile> -OF<outputfile> -OO -OS -NL -FF|D|R -PC|Q|D|R

Some combinations of parameters are illogical. If the supplied
parameters don't make sense ALex may display an error message and then
exit - eg: specifying more than one output file. In other cases, such as
specifying two or more format parameters (i.e. -F parameters) ALex will use
the last (i.e. right-most) one listed on the commandline.


Help
----
You can get a brief list of options on-screen by typing alex -help (or
alex -? ).

Note that the -help parameter disables any other parameters included on
the commandline. If other parameters are specified as well as -help they
are ignored -- ALex will just display the 'help' screen and then exit.


Input file
----------
You can omit the file extension for the input filename. If a file with the
supplied filename isn't found, ALex will search for filename.ala and
then filename.alan. (Please note that filename.alan won't work with the
DOS version of Alex. You'll need to specify the short DOS format name for
the file - see the Usage section above.) 

If the input file is in a directory other than the current one, you can
prepend the directory name to the filename -- eg:

    alex ..\source\mygame.ala
    alex d:\alan\mycode\mygame.ala

    
Output file
-----------
If no output filename is supplied, the output file will be called
filename.txt. To specify an output filename, use the -OF switch followed by
the required output filename (a space after -OF is optional) - eg:

    alex mygame -OF spelling.chk
    alex mygame -OFspelling.chk

Any existing file with the same name will NOT be overwritten unless the
"overwrite output file" option is specified (with the -OO switch.)

If there's no '.' in a specified output filename, ".txt" will be added
automatically. If you don't want that, add a '.' at the end of the name.
That is:
    -of junk  = output file called junk.txt
    -of junk. = output file called junk

By default, the output file will be written in the directory where the source
file is located. If a different directory is required it can be prepended to 
the output filename. For example, the following command will read mygame.ala 
from the current directory but write the output file in the directory c:\temp

    alex mygame -OF c:\temp\mygame.txt


stdin/stdout
------------
Note that ALex can read from stdin and write to stdout. (If you don't
know what I'm talking about, don't worry - ignore this section!)

If no input filename is specified ALex will read its input from stdin
and, unless an output file is specified with -OF, write its output to stdout.
If you want to read a specified input file but send output to stdout use
the -OS switch. You might want to do this so that you can pipe the output
through a commandline spellcheck utility such as Unix's "spell" - eg:

    alex mygame.ala -OS | spell


Overwrite Output
----------------
Use the -OO switch if its okay for ALex to overwrite an existing
file with the same name as the specified (or automatically calculated)
output filename. (That's "oh" "oh" - short for Overwrite Output - not "zero"
"zero".)  For example, the following command will overwrite the output file
mygame.txt in the current directory if it exists:

    alex mygame -OO


No Line numbers option
----------------------
The -NL switch means no line numbers will be printed in the output file.
This switch overrides the default behaviour which is to display source
code line numbers at the start of each piece of text in the output file.

eg:
Default formatting style

    134: The quick brown fox jumped over the OBJECT
    to the north.
    139: The western door is guarded by the fox. You
    can only go east or south.

No line-numbers formatting style

    The quick brown fox jumped over the OBJECT to
    the north.
    The western door is guarded by the fox. You can
    only go east or south.



Text Format control codes options
---------------------------------
By default, ALex uses the ALAN format control codes - such as $p and $t 
- in the source code to format the output file. For example, $p inserts a 
blank line in the output file; $t is converted to four spaces in the output 
file.

You can change the way ALex treats format control codes by using the -F 
switch. There are three options - 

    -FF = format the output with the format codes (i.e.: the default)
    
    -FD = display the format control codes in the output file
    
    -FR = remove the format control codes (i.e.: neither format the 
    output text using the format codes nor print the format codes in the
    output file)
    
ALex processes the following format control codes 
     $p - insert a blank line
     $i - new line and indent four spaces
     $n - new line
     $t - indent four spaces
     $$ - no space
   
        
Player command parameter control codes 
---------------------------------------
By default, parameter control codes from the source code are printed as 
uppercase words in the output file. For example, $o is displayed as OBJECT, 
$1 as FIRST.

You can use the -P switch to change the way ALex processes parameter 
control codes. There are four options - 

    -PC = convert codes to capitalised words (i.e.: the default)
    
    -PQ = convert codes to lowercase words in single quotes (eg: $o becomes 
    'object'; $1 becomes 'first')
    
    -PD = display parameter codes (i.e.: just print the codes in the output 
    file)
    
    -PR = remove parameter codes (i.e.: parameter codes are neither converted 
    to text nor printed in the output file)

ALex processes the following parameter control codes
    $o - object 
    $v - verb
    $a - actor
    $l - location
    $1 - first parameter
    $2 - second
    $3 - third
    
(Any $ codes that aren't in the format or parameter control code lists are 
simply printed in the output file as they are written in the source code
file.)


Some examples
-------------
The following examples of ALex commands illustrate some of the most
likely combinations of commandline switches.

The simplest example just states the filename to be read from (and so ALex
will create a file named "mygame.txt" to contain the output):
    alex mygame

A common use would be to run ALex (with the all the default format options)
and write the output to an existing output file (called, in this example,
"mygame.txt"):
    alex mygame -oo

I also expect often there'd already be a file with the default output
name of mygame.txt, perhaps a 'readme' file about your game. So you'd need
to specify another name for the ALex output file. With this example ALex
would output to a file called "spellchk.txt" - overwriting any existing file
of that name:
    alex mygame -of spellchk -oo

I also expect a lot of people might want to turn off the output text
formatting (done with -fr):
    alex mygame -of spellchk -oo -fr

And to get a very clean-looking output perhaps remove the line numbers too:
    alex mygame -of spellchk -oo -fr -nl


Using the output file
---------------------
My intention is that the output file can be opened in a word-processing 
program and then spellchecked. I imagine people using MS Windows could have 
the source code open in their text editor at the same time and could switch 
back and forth between the wordprocessor and the editor windows fixing
spelling errors in the sourcecode as the wordprocessor highlights them. 

If your computer operating system doesn't switch between programs you could
simply note down errors and line numbers and then edit the source code later.

You could also print the output file and read it away from the computer. I 
find this a helpful way to see errors or clunky writing that aren't so 
obvious when buried in the programming code of the original source file.
    

--------
Feedback
--------

I welcome your comments, bug reports and suggestions for improvements or
new features.

My Internet email address is sg@xtra.co.nz

Also contact me for the ALex source if you would like to port this program
to another operating system.



---------
Copyright
---------
ALex is copyright, 1999, by Stephen Griffiths.

This software is provided free of charge. It can be distributed freely as
long as this text file, including this copyright notice, is included with
the executable file. This software has no warranty of any kind.


                        --------------------------------
    
