-------------------------------- 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 .txt. If a file called .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 -OF -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. --------------------------------