QTads v1.7 - An interpreter for Tads games.
Written and maintained by Nikos Chantziaras.  Based on Mike Roberts'
portable reference implementation of Tads.

This file contains an overview of QTads.  Other documentation files in
the distribution include:

    AUTHORS
      People who wrote QTads' code.

    BUGS
      A list of known bugs.  You shouldn't report them.

    COPYING
      The GNU General Public License (GPL).  QTads is distributed under
      the terms and conditions of this license.  (Note that this file
      might be missing in the Debian distribution; it can be found at
      /usr/share/common-licenses/GPL-2 or in the "Help->About" menu of
      the program.)

    CREDITS
      People who contributed to QTads in one way or another.  Help me
      make QTads better and your name will appear there too!

    INSTALL
      Installation and usage instructions.  The first thing you should
      read (after this README file).

    NEWS
      Contains the list of changes between QTads versions.

    PORTABILITY
      A list of systems and compilers where QTads is known to run
      (few), and also those where it is supposed to run (many).

    SOURCE_README
      If you want to contribute code, read this.

    TIPS
      Contains some useful information.  Make sure to check it out.

    TODO
      Features/enhancements that are planned to be added.  Help is more
      than welcome.

    qtads.6.gz
      Manual page (compressed with GNU Zip).  This won't actually get
      installed.  It's for people who want to create RPM or Debian
      packages for QTads.  (If you installed QTads by using such a
      package, it might have been installed.)

The newest version of QTads can be downloaded from its homepage at:

    http://qtads.sourceforge.net

Previous versions can be found at the project page:

    http://sourceforge.net/projects/qtads


About Tads and QTads
====================

QTads is a so called "interpreter" for games created with the Text
Adventure Development System, or "Tads" for short, a C-like object
oriented programming language for authoring Interactive Fiction
(similar to the Infocom or Legend Entertainment games, like "Zork").
Yes, we are talking about text adventures here.

The Tads compiler creates executables for the Tads Virtual Machine (the
"Tads VM").  QTads is an implementation of this Virtual Machine; it
runs Tads VM executables.  One can also say that QTads is a Tads VM
emulator.  This is similar to Java; the Java compiler creates JavaVM
programs which must be executed with a JavaVM implementation.

Both Tads 2 as well as Tads 3 games are supported.  Note that the
Tads 3 support is not complete at this point; QTads lacks banners
(which means there is currently no exit-list below the statusline) and
timed input (Tads 2 timed input works fine).  The vast majority of
games will play fine, but some may not.  Work is being done to make
QTads feature-complete.

QTads is not written from scratch; it uses Mike Roberts' portable
reference implementations of the two Tads VMs; the T2 VM (written in C)
and T3 VM (written in C++).  The portable implementations are intended
to be embedded in applications; they cannot be executed on their own.
They're function libraries that require an external I/O interface.
This external interface (along with other useful things) is implemented
by QTads with C++ using Trolltech's Qt library (this should explain the
"Q" in "QTads").

For more information about Tads, visit its home page:

    http://www.tads.org


What is Multimedia Tads?
========================

Multimedia Tads (also known as "HTML Tads") is an extension of Tads
that uses HTML to implement multimedia capabilities.  Multimedia Tads
is not an extension of the two Tads languages (Tads 2 and 3), but
rather of their output system.  Although QTads doesn't support most of
the HTML extensions (but it supports more HTML tags than most other
text-only interpreters), it *can* execute games that use HTML; on the
binary level, Multimedia Tads and "plain" Tads executables are actually
the same thing.  You won't see any graphics nor hear sounds/music, but
the game will play just fine.  In Tads 2 games, you also won't see any
banners that the game would otherwise display (Tads 3 games don't use
HTML for banners; hopefully, future versions of QTads will provide full
banner support for Tads 3 games).  The vast majority of games don't use
the multimedia extensions though.  But as already mentioned, you can
play even those games in QTads.

There's another Tads interpreter maintained by me called "HTML QTads"
that fully supports the multimedia extensions, but it has not been
released yet.  (It's one of those "Real Soon Now" projects.)  The only
way right now to play Multimedia Tads games on X11-machines is to use a
Windows emulator to run Mike Roberts' "HTML TADS" interpreter (newer
versions of Wine are known to work).  I hope I can finish HTML QTads
soon.

Now, you may ask yourself why I released QTads when a full multimedia
interpreter will be available "soon".  The answer is that multimedia
interpreters lack one single feature that many players (including me)
consider quite important: text-justification.  Being able to
block-justify the game's text is only possible in a text-only Tads
interpreter.  It could be that this feature will be added to Multimedia
Tads at some point; until then, QTads will continue to exist.  And
besides, most games don't use the multimedia features, or use only a
small subset that is already available in QTads.  For those games,
QTads is everything you need.


Features
========

Here's a list of common (and uncommon) features in QTads, in no
particular order:

  * Configurable text justification.

  * Text-color support for Tads 3 games.

  * Margins.

  * Font anti-aliasing.

  * Full Unicode support for Tads 3; you can play games written in any
    language.

  * Multimedia Tads character entities, which means that typographical
    quotes, dashes and other special characters are available in both
    Tads 3 as well as Tads 2.

  * Support for Tads 2 character mapping files.  Most Unix interpreters
    can't run games that use this Tads 2 feature; QTads can.

  * Typographical apostrophes and dashes in every game (can be
    disabled).  This enhances the display of games that don't use
    character entities.

  * Internationalization support; as of this writting, QTads speaks
    English and German.

  * Fullscreen mode with removable menu-, tool- and scrollbar.

  * Timer on the statusbar (can be disabled).  Useful for IF-Comp games
    that must be played for two hours.

  * Themes; you can save your settings in "Themes" and switch them at
    runtime.

  * Soft scrolling; game text doesn't just pop-in in the window, but
    scrolls (can be disabled).


Is it "TADS", or "Tads"?
========================

Who cares?

Okay, if you *do* care, the author of Tads (Mike Roberts) spells it
"TADS", but since I don't pronounce it as "t, a, d, s," I refer to it
as "Tads", which rhymes with "bads" (not that "bad" has a plural).


Bugs, bugs, bugs
================

(Bugs?  What bugs?)

QTads is pretty stable, thanks to the BugFree(TM) reference
implementation that has been improved and maintained by Mike Roberts
for about 10 years now (and still is).  Most bugs in QTads are expected
to be in its GUI-code.  Please report any bugs to the author's
email-address (see below).


On what systems does it run?
============================

Theoretically, it should run on *any* system for which a Qt-port exists
(many Unices, including MacOS X, Windows, even embedded devices like
cell phones and PDAs using a Linux framebuffer with Qt/Embedded or
X11).  But since the world isn't perfect, I guess it runs only on
Unix-systems.  No big deal actually, since the whole point is to have a
GUI Tads-interpreter for Unix (note that "Unix" includes MacOS X);
Windoze and pre-X Mac OS already have good interpreters (as for the
cell phones, well, that's another story).  But if you manage to make
QTads run on a non-Unix system, I would be *very* interested to hear
about it.  For a somewhat half-assed attempt to create a list of
systems where QTads is supposed to run, see the file PORTABILITY.

Note that it's not possible for me to compile QTads for Windows, nor to
release Windows executables of QTads.  Sorry, but the Windows port of
the Qt library is not freely available.  No freedom (with capital "f"
or not), no QTads.  Folks with a commercial Qt license willing to
provide this service to the IF community are more than welcome though.
(In case you wonder, at the time of this writting, a commercial Qt
license costs about $4000; as a friend of mine said, "I might buy two,
in case I leave one in the bus."  If you want to donate a license, be
my guest; it's quite cheap <g>.)

QTads is currently being developed on a machine with the following
configuration:

    Celeron D 2.40 GHz with 768MB RAM
    Linux kernel 2.6.4
    GCC 3.3.3
    Qt 3.3.1
    XFree86 4.3.99.902
    Linux Distribution: SuSE Linux 9.1

Before October 2004, the following system was used:

    Pentium II 400MHz with 192MB RAM
    Linux kernel 2.4.17
    GCC 3.2.1 and 2.95.3
    Qt 3.1.2
    XFree86 4.0.3
    Linux Distribution: SuSE Linux 7.2

Before August 2003, the following system was used:

    Pentium 133MHz (non-MMX) with 32MB RAM
    Linux kernel 2.4.17
    GCC 3.2.1 and 2.95.3
    Qt 3.1.1
    XFree86 4.0.3
    Linux Distribution: SuSE Linux 7.2

It ran surprisingly well on the ancient machine, especially with Tads 2
games, and is extremely fast on the Pentium II, but I don't recommend to
use it on something like a 386.  Using a text-mode or the XGlk Tads
interpreter is a much better option in this case.  (Of course you're
free to try QTads even on a 386, but don't blame me if it won't be able
to move its legs; it won't be much faster than any other Qt application
on such a system, if they run at all).  It could be that it runs at an
acceptable speed on a fast 486, but I didn't try it myself.  Reports
are welcome.  In order to increase speed, you should use small
font-sizes (below 14pt), a low resolution or a small window, disable
font anti-aliasing and use only left-justified text.  Using
bitmap-fonts may also help.  But as already mentioned, better use the
XGlk or text-mode interpreter in this case.


Who wrote this thing?
=====================

QTads is the work of an Interactive Fiction maniac with the funny and
impossible to spell and pronounce name "Nikos Chantziaras".  He's from
Greece (whatasurprise) and wrote QTads because (unlike Windows and
pre-X MacOS) Unix lacks a good GUI interpreter for Tads games.  He is
sometimes known for talking about himself in the third person (how
silly that is!)  He maintains a small Interactive Fiction related
homepage at:

    http://members.lycos.co.uk/realnc/

which is full of banners and pop-ups, gets updated quite less than
often and might disappear at any moment, and his e-mail address is:

    realnc@users.sourceforge.net

Bug reports and questions should be sent there.  He always answers them
all (but not immediately, since he's using a shared/public computer for
net-access).  If you're Greek, please don't use "Greeklish", if
possible, since he finds it hard to read (ti to exoume to Unicode
alwste?)  You can also talk to him in German, weil Deutsch rein
zuf�llig seine zweite Muttersprache ist :)


What's Interactive Fiction?
===========================

Well, this is just a poor README file and therefore not the appropriate
place for an introduction to Interactive Fiction.  For more information
about Interactive Fiction (or "IF" for short), just go to the Tads page
(see above) and follow some links.  Or go to the Google search engine
(http://www.google.com) and search for "interactive fiction"; you'll be
amazed about how many results you'll get.  And you'll be even more
amazed about how active the IF community is.

There are two Usenet newsgroups for IF related things.  The first is
RGIF, which is short for:

    rec.games.int-fiction

where people are talking about IF games in general; things they like in
games, things they don't like, things they hope to see in future games,
requests for hints and solutions, reviews of games, announcements of
new games/software or happenings, flames (mostly funny ones; keep
this in mind when you "flame" ;-).  Stuff like that.

The other newsgroup is RAIF, which stands for:

    rec.arts.int-fiction

This newsgroup is for everyone who is interested in creating games.
Most IF authors use to hang around there, so this newsgroup is an
excellent place to post questions about IF theory, authorship and
programming.


Where do I find games for QTads?
================================

As I said above, the IF community is a very active one.  New games are
released all the time.  There's a large repository for IF-related stuff
(with *lots* of games!) called "The Interactive Fiction Archive".  You
can access it by HTTP:

    http://www.ifarchive.org (very slow)

or by FTP:

    ftp://ftp.ifarchive.org (also very slow)

The archive has mirrors that are usually much, much faster, like:

    http://mirror.ifarchive.org (faster than light)

Which, at the time of this writing, is the fastest of all.  Please use
the mirrors instead of the main archive!  You'll save yourself (and
others) quite a few headaches.  (The full list of mirrors is displayed
in the main archive's title-page.)

Since the archive is actually just a (huge) bunch of data thrown
together (more or less), a nice fellow has created a site that will
guide you through the archive.  The site is called "Baf's Guide to the
IF Archive" and is located at:

    http://wurb.com/if

It contains many cool things, like a "Genre Map" for the games
located in the archive along with descriptions, reviews and ratings, as
well as many useful links.


I don't like QTads.  It sucks.
==============================

Then help me improve it.  Send me suggestions and bug reports, or even
code if you know C++ and Qt.  Now!  Don't be afraid to do it.  Thank
you.


OK, I'll send some code.  How do I do this?
===========================================

If you decide to send me code, please read the SOURCE_README file first
(not needed for small amounts of code).  Also, drop me a mail to inform
me on what you're working on (this is to ensure that we won't be trying
to solve the same problem or add the same feature).

Files should be compressed with bzip2 or gzip (or even zip or rar)
using the highest compression level and sent to my email address at
SourceForge:

    realnc@users.sourceforge.net

You can send whole files or simply diffs created with (guess) the
`diff' utility.  I also accept diffs created with `xdelta'.  With
`diff', use either the -c or -u option, *not* the default (-e) to
generate the patches.  Here's an example, where "qtads-1.7" is the
directory containing the original 1.7 sources, and "qtads-modified" the
directory with your modified sources:

  diff -Naur qtads-1.7 qtads-modified > patch
  bzip2 --best patch

This will create a file "patch.bz2" containing your modifications.  The
general format of the `diff' command is:

  diff -Naur ORIGINAL_DIRECTORY MODIFIED_DIRECTORY > PATCH_FILENAME

Do not include a slash ("/") when specifying the directories.

If your code is good (which means: if it doesn't suck the way my own
does ;-), I'll include it in the next version.  Note that your code
will be placed under the GPL.  Since QTads is a simple interpreter for
Tads games and not a nuclear war simulator, I'm not requesting signed
forms from your boss/school/etc.  Just send the damn code, will ya? ;-)


Copyright
=========

QTads is Copyright (C) 2004 by Nikos Chantziaras.

QTads 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.

QTads 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