***************************************************************

Welcome to the TADS Source Code Example Collection Readme File!

***************************************************************

 ftp://ftp.gmd.de/if-archive/programming/tads/examples/Readme

Note that the if-archive is mirrored at a number of other sites,
including the US:

 ftp://ftp.wustl.edu/doc/misc/if-archive/

and Canada:

 ftp://ftp.io.org/pub/mirrors/if-archive/


Version History:
Version 1.0 - 10/6/93. Written by N. K. Guy. ([email protected])
Version 1.1 - 10/20/96. Updated TADS information & email addresses,
laced file with URLs.


WELCOME
Welcome to the TADS Source Code Example Collection! This directory
in the if-archive directory on ftp.gmd.de contains a veritable
treasure trove of code examples written in TADS, the Text Adventure
Development System.

You're welcome to submit your own pieces of useful TADS code to this
area. We ask you take the time to read through these guidelines,
however. The interactive fiction (if-archive) archive on ftp.gmd.de is
moderated by Volker Blasius ([email protected]) and David Kinder
([email protected]) but please note that neither they nor
N. K. Guy ([email protected]; the author of this readme file) are
responsible for the accuracy of any files in the directory.


ABOUT TADS
TADS is a particularly groovy freeware system for programming text
adventure games, available for a variety of computer platforms. It was
originally a shareware package published by High Energy Software, but is
now a freeware release owned by its author, Michael J. Roberts. You can
find the latest and greatest version of TADS in a variety of places,
including:

 ftp://ftp.gmd.de/if-archive/programming/tads/

For discussions on the topic of writing interactive fiction, check
out the Usenet group:

 news:rec.arts.int-fiction

For discussions on the
topic of playing interactive fiction games, check out the group:

 news:rec.games.int-fiction


GUIDELINES FOR THE TADS EXAMPLE COLLECTION
Here are the guidelines for submitting files to the TADS Source Code
Example Collection.


SUBMIT WORKING CODE
When submitting files for this Examples directory please submit only
working bits of TADS code that you can actually paste into your
favourite text editor and use. Pseudocode or mere ideas for neat
routines should not be put here. It's probably more appropriate to post
those to a public forum like the Usenet news group rec.arts.int-fiction
for public discussion.


DEBUG YOUR CODE
Remember that it's quite likely that hundreds of people from around
the world may be downloading your code and trying it out. So try to
test your code thoroughly before uploading it - don't just type it
up in the heat of inspiration and submit it before compiling it.
This is just a publicly accessible storage area. There aren't crews
of people hired to check out all contributions. There isn't really
anybody screening submissions for bugs, in fact!

(That suggestion may sound condescending, but it *is* very easy to
make tiny mistakes. I was putting together some sample code to
post along with this file, and rewrote one line of it, forgetting to
close a parenthesis in the process. I was going to post it when I
decided to practice what I preach and compile it. And got a string of
TADS-300 errors...)


COMMENT EVERYTHING
Comment everything profusely. Remember that everything following the
// symbol or bracketed by /* and */ is ignored by the TADS
compiler. So you can put comments explaining the finer points of
your code right into the file itself. Not everyone is necessarily a
TADS whiz, so always explain any interesting or unusual techniques.
This is meant to be an educational facility as well as a potent
breeding ground for new ideas, to mix clumsy metaphors.


IDENTIFY TADS VERSION NUMBER
Always identify the version of the TADS compiler you used to compile
your code. There are significant improvements in TADS from release to
release, and a piece of code that works swimmingly on a newer compiler
may not work at all on an older one. (though the reverse is less likely
- Mike Roberts has always made a great effort to ensure that new TADS
releases can compile older code) Reduce confusion - always identify your
TADS compiler version number. (This is the number that appears onscreen
whenever you compile a TADS game.)


AVOID MACHINE-DEPENDENT CODE
Avoid platform-dependent code. For example, some computers let you
use extended characters that include non-English accents and other
symbols. These characters are usually not directly convertible to
other computers. Remember that TADS .GAM files are totally portable
between all the systems on which TADS runs if you avoid such
machine-dependent features. Why limit your potential user base?

So, avoid machine-specific features - particularly those that rely
upon user exits - if possible. If you have a particularly neat
machine-dependent hack you want to share, by all means do so. But
please identify this clearly.


POST EXAMPLE CODE, NOT ENTIRE GAMES.
The purpose of this file area is to maintain a collection of useful code
segments and ideas for educational purposes. If you're submitting a
complete game, consider submitting it instead to the general TADS source
code section, which can be found at:

 ftp://ftp.gmd.de/if-archive/games/source/tads/

There are lots of complete games available in source form here.
Additionally you should consider submitting a playable .GAM file for
inclusion in:

 ftp://ftp.gmd.de/if-archive/games/tads/


SUBMIT FILES IN TEXT OR ZIP FORMAT.
Plain ASCII text is the lowest common denominator for all personal
computers. You know that a plain ASCII file with no extended
characters or other machine-dependent formatting is going to work
with any system that can run TADS. However sometimes it's not
convenient to submit a single text file. In that case combine all your
files using the "zip" format.

There are unzipping utilities available for all of the computers that
can run TADS. Many of these utilities are available at ftp.gmd.de
itself, in:

 ftp://ftp.gmd.de/if-archive/download-tools/


POST SECTIONS OF CODE, NOT BIG FILES
Let's say you have a clever piece of sample code that involves a small
change to the "adv.t" file that comes with TADS. Don't simply make this
change and then submit the entire modified "adv.t" file. This is a waste
of space, means that people have to wade through pages of unchanged code
and isn't terribly useful. Rather, just comment each section of code as
appropriate. "This function should go into your adv.t file," or "This
new variable should go into your std.t file," etc.

Remember also that, beginning with version 2.1, TADS can replace or
modify specific portions of the "adv.t" file without you having to
rewrite the whole thing. Consult the "TADSVER" file that came with
your copy of the TADS compiler, or read the 2.1 release notes at:

http://www.tela.bc.ca/tela/tads-manual/tads21.html


KEEP LINES SHORT.
Try to keep the lines of text in your sample to fewer than 70 to 75
characters long. Some editors automatically wordwrap longer lines.
This can be catastrophic when you then go to compile the code, as a
commented line may wrap around to the next line. This will confuse
the compiler no end. So, keep lines in your file short and there
should be no problems.


PUT COPYRIGHT NOTICES, ETC.
Try to put a brief note at the top of the file concerning the legal
status of the code. If you're just writing the stuff for fun and want
to put it into the public domain, say so. Or you may want to claim
copyright to it if you are wholly responsible for the content, but
allow others to use it. Some people like the GNU copyleft agreement
used by the Free Software Foundation, and include variants on that.
Regardless, you should make sure it's clear who, if anyone, owns the
file.


SAMPLE CODE
For examples of a suggested format, take a look at the
files "shoc.t" and "wizard.t".

Have fun!

- N. K. Guy