*************************************************************** 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. (tela@tela.bc.ca) 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 (blasius@gmd.de) and David Kinder (kinder@teaching.physics.ox.ac.uk) but please note that neither they nor N. K. Guy (tela@tela.bc.ca; 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