This filter is based on outputFilter.t by Iain Merrick.
Modified by Nikos Chantziaras (realnc@hotmail.com).
Release date: 4 Sep 2002



Modifications to the original code
==================================

    - Line break is ^^ instead of ^
      ^^ is more unlikely to occur in normal text.  It also fixes the
      bug where \^ (capitalize next character) is printed as \b
      (visible, not line break).

    - Indent is ~~ instead of ~
      ~~ is more unlikely to occur in normal text.

    - Emphasis is //emph// instead of _emph_
      This is based on an old convention (/emph/).  I use "//" because
      a single "/" is very common in normal text.

    - Added __bold__
      As with the others, __ is more unlikely than a single _.

    - Because of the above modifications, the bug where the user typed
      "_", "~", etc, at the prompt is now fixed.  Typing say "__" still
      results in wrong behavior though.

    - Added {{text in quotes}} to <q>text in quotes</q> conversion
      Nested quotes work as expected: {{text {{in}} quotes}} will be
      converted to <q>text <q>in</q> quotes</q>.  There's no limit to
      how deep you can nest.

    - Removed ... -> . . . conversion
      Because it breaks hyphenation (sometimes the dots appeared on
      different lines, which is not what we want.)

    - Changed verb grammar
      Now, ON and OFF are used to enable/disable the special features.
      Entering the verb without ON/OFF displays the current status.

    - Added "quotes" verb to enable/disable apostrophe to "&rsquo;"
      conversion.

    - The locals inEmph, inFmt and inTag are moved into global
      This allows printing HTML-code in chunks (I hope).

    - Added global.inBold
      Just another state, like inEmph or inTag.

    - Added global.convertApostrophes
      The "quotes" verb changes this to nil or true to enable/disable
      apostrophe conversion.

    - Added global.skipFilterOnce
      Set this to true to disable the filter for just one output.  The
      filter sets this back to nil automaticly.

    - Fixed "'" -> "&rsquo;" conversion
      The original code did not replace the apostrophe "'" with
      "&rsquo;" because of a typo in the original code.  This has been
      fixed.

    - Disabling double-spacing and indentation at the same time is not
      allowed anymore.  This makes sure that the text is always
      readable.

    - Added enableFilter() and disableFilter() functions.  Call these
      to enable and disable the filter.

    - The showcontcont() function from adv.t is replaced and the room
      class modified.  If your game replaces showcontcont(), things
      will break.  Also the check the modification to the room class,
      and adapt the code to your game (if you need to).

    - The filter is now a bit more optimized (it should run now at
      double speed).  On my P133, printing the instruct.t help text
      takes 18 seconds.  The original code needed 37 seconds.  (Still
      too slow, but better than without a filter at all.  Because of
      this, any large text should be printed in small chunks.)  Note
      that the algorithm is still almost the same.  The problem was
      that Iain's code was intended as an example.  I just inserted a
      few optimizations here and there to make it a bit more suitable
      for real-life usage (and less suitable as a pure example).



Instructions
============

(This is the original documentation by Iain Merrick, modified to
reflect the changes.)

outputFilter.t is a module that defines an output filter function
which makes it easier to use some fancy HTML-TADS formatting tricks.
I haven't come across any other sample output filter code, so I thought
people might find this useful.

The module is almost "plug and play".  Just include it in you game
after the main Tads library files:

#include <adv.t>
#include <gameinfo.t>
#include <std.t>
#include <outputFilter.t>

To use it, first make sure you're in HTML mode (by printing "\H+").
The commonInit() function is a good place to do this.  Then you just
need to add the following call:

    enableFilter();

(Note that _all_ TADS interpreters since version 2.3 understand HTML,
not just multimedia interpreters, although text-only terps will simply
ignore most tags.  So there's no need to avoid HTML just because you're
using a text-only interpreter.)

Once installed, the filter modifies your game's output as follows:

 *  Apostrophes are changed to '&rsquo;', the curly-right-quote entity.
    This makes words like "isn't" look much nicer.  Note that not all
    interpreters support this.

    This feature is turned off if global.convertApostrophes is nil.
    This is exactly what the verb QUOTES OFF does.

    (If you actually want to put quotes around a word, you should use
    the {{ feature, as described below.)

 *  Two underscore characters toggle the '<b>' tag, so you can write
    stuff __like this__ to highlight a word or phrase (it will be
    converted to <b>like this</b>).

 *  Two slash characters toggle the '<em>' tag, so you can write stuff
    //like this// to emphasize a word or phrase (it will be converted
    to <em>like this</em>).

 *  Two braces ("{{" and "}}") toggle the '<q>' tag, so you can write
    stuff {{like this}} to put text inside quotes (it will be converted
    to <q>like this</q>).  Nested quoted text works as expected; {{text
    {{in}} quotes}} will be converted to <q>text <q>in</q> quotes</q>.
    There's no limit to how deep you can nest.

 *  '--' is changed to '&endash;' and '---' is changed to '&emdash;'.
    This is stolen from LaTeX, where I find it a very handy feature.

 *  '^^' is expanded to '<p>' and '~~' is expanded to '\t'.  The point
    of this is that you can easily change this behavior at runtime, as
    in the Adventions games: I've supplied two sysverbs, 'space' and
    'indent', to demonstrate this.  Note that you can never disable
    both indentation and double-spacing at the same time.  One of them
    has to be active, or the text will be very unreadable.

    ^^Now you can start blocks of text like this.
    ^^~~And start each new paragraph like this.
    ^^~~And the user can change adjust the formatting to his/her taste.

    The Adventions games seem to use functions called 'P()' and 'I()',
    which strikes me as being a bit cumbersome.

Escape sequences, HTML tags and format strings are not modified (but
format strings will be passed through the filter after evaluation).  If
the filter gets confused when you print out a lengthy HTML tag in small
chunks, you may want to turn it off with disableFilter(), or set
global.skipFilterOnce to true before outputting each chunk.  Please
e-mail me (Niko, not Iain) if this happens, since the code is intended
to avoid this (consider it a bug if it happens).

You might not want to use all of these features -- you might need to
use '__' or '^^' as ordinary characters, for instance -- but it's easy
enough to turn some of them off: just follow the comments and delete
the relevant chunk of code.

This module was written by Iain Merrick.  I [Iain] didn't know anything
about output filters until Stephen Granade sent me some code for
changing apostrophes into &rsquo;'s, but this code isn't derived from
his.



Tips
====

Don't prepend the "^^~~" sequence to your actor's actorDesc property.
This is done automaticly.

You can prepend the "^^~~" sequence to the heredesc property of a
fixeditem if you need to seperate it from the room's long description.

Never prepend the ldesc property of a room with "^^~~".  Override the
dispBeginLdesc property of the room class if you want to do something
else than the default (which is a "\n~~" sequence).

Examples:

  home: room
    ...
    ldesc = "Fred's house is small. It must be tough living in the
      Stone Age.
      ^^~~Of course you can use the paragraph seperator sequence if
      your ldesc has several paragraphs. "
    ...
  ;

  foo: fixeditem
    ...
    ldesc = "It's a common foo.
      ^^~~This is the second paragraph of the foo's ldesc property. "
    heredesc = "^^~~On the corner there's a foo. And we should use the
      paragraph seperator if we want to seperate this description from
      the room's ldesc. "
    ...
  ;

  fred: actor
    ...
    ldesc = "He is sitting on his couch, watching TV. "
    actorDesc = "Fred is here, watching cartoons. "
    ...
  ;

Just play around with the new features.  Sooner or later, you'll get
the feel for it.



Known bugs
==========

The command:

  >say "__"

will cause subsequent text to be displayed in boldface.  Same goes for:

  >say "//"

and

  >say "{{"

will cause quotes to be displayed wrong.  I'll fix this later ;)
