                                JFTerm
                                ======
Version 1.22 (11 Jun 1998)

Introduction
------------
JFTerm was really the test for DispLib (and hence uncovered lots of little
buglets all crawling around and hoping for a nibble of my important data),
and a solution to the problem of there being no talker client for the Arc at
the time. Since then JFTerm has improved dramatically.

JFTerm is the only IRC-Chat-Talker-MUD client available on RISC OS. It may
be a jack of all trades and a master of none, but it is one of the simplest
clients around. If you want to talk on the Internet from your Acorn you
should use JFTerm.

That's the advert over with. The truth of the matter is that I truely believe
that JFTerm is good. There are places where it is lacking, but it suffices.
I use it in preference to all other clients presently available for RISC OS.
[That doesn't mean that I don't like them, just that even with the features
 they provide JFTerm comes out top in my opinion].


The Iconbar
-----------
When you run JFTerm it will put an icon on the icon bar. This is very useful
because by clicking on it you can connect somewhere. Without it you wouldn't
be able to tell it to connect anywhere and it'd just be a waste of memory.
It's a good job that most programmers don't forget to put things on the
iconbar, isn't it ? (sorry, Jogu I couldn't resist :-) ).

The iconbar menu has six options :

Enable proxy : Enables the proxy (see later)
Connect...   : Opens the 'Connect' window
Finder       : Leads to a list of connections active; selecting one will open
               it's window at the front
Close        : Leads to a list of connections active; selecting one will
               close the connection
Libraries... : Opens information window about the current libraries
Sites...     : Opens the 'Site editing' window

Clicking on the Iconbar with Select will bring up the 'Connect' window,
whilst Adjust will give you the Sites edit window. To connect to a site you
can either select from the menu of sites (beside the host name), or by
entering the host name and port you want to connect to. Pressing Ok will
start the connection; if the host could not be resolved a message will appear
telling you so.


The Connection window
---------------------
This should pop up as soon as the connection is started. If the host is not
accepting connections (or it failed to respond in time) an error will be
displayed in this window and you should close it. If the connection is made
successfully a little pane will appear below the window allowing you to enter
lines to send to the talker. Whatever the talker sends to you will be
displayed in the window above. The normal writable icon style keypresses all
work as you'd expect, with the exception of up and down which will move
backwards and forwards in the history respectively.

Pressing Menu over the connection window gives you a number of choices :

Save       : Leads to a box from which you can save the text from this window
Edit       : Allows you to :
  Clear           : Clears the display and forgets everything that was in it
  Clear selection : Lose the current selection
Display    : Allows you to :
  Font            : Change the current font
  Size            : Change the font size
  Save            : Save the current font and size as the default
History... : Opens the History window for this connection
<style>    : Presents a submenu generated by the style.
Speak text : Speaks everything as it is displayed.
Disconnect : Does just that

If you close the window, you can quite easily retrieve it by using the
iconbar menu 'Finder' option.


The History window
------------------
This doesn't do much at present except show the history. Double-clicking on a
line will re-enter it for you.


Libraries window
----------------
This lists the currently installed libraries. Clicking menu over the
libraries name will (if the library supports it) allow you to change it's
configuration or other options. This is still experimental.


The Site editing window
-----------------------
This is a very simple editing window. Don't expect too much. Basically you
can edit the sites list from here. Use the arrow buttons (or Page Up/Page
Down) to select the entry to modify, or go past entry '1' and you can get a
blank entry. When you've finished changing it, press Update. To delete an
entry, press Delete. If you want to re-order the entries they you'd better
edit the Sites file by hand 'cos I've not worked that out yet... The lower
the entry number the nearer the top of the menu it will be.


Styles
------
'Styles' in JFTerm are the different ways in which you can access things.
There are currently four styles defined (and one modification to a style) :

Default : This is the standard 'raw connection' style which has support for
          colours and stuff. This will probably be the one you use most.
Finger  : This is used for when you finger people. It's really just a demo
          of what you can do in relatively little code to add a prompt.
          There is also a Finger:Bold extension style which is used to colour
          things green and bold things before colons. This is still
          experimental. Try fingering jrflet@sunlab1.essex.ac.uk.
          Finger URLs should also work if they are of the form :
            finger:[//][<user>@]<machine>[/W]
IRC     : This is style is used to connect to IRC and talk on a single channel
          (or with one person). See the the accompanying file which documents
          the IRC style.
Chat    : This is a style used for a direct chat session with somebody.
          Although I couldn't be bothered to implement an 'as you type' chat
          style connection, this gives you a reasonable line based chat
          session.
          When started, it will listen on the TTYLink port (87) for incoming
          chats. Such requests will open a new window immediately. If you don't
          want to be contactable then disable the option in the Libraries
          window.


Things to try
-------------
Why not try '.set terminal colour' if you use Oaktree - emmensely groovey :-)
I'll not go into great lengths about how amazed I was to see colour for the
first time, but suffice to say I was a little bit bouncy, bouncy, bouncy,
fun, fun, fun, the wonderful-wonderful thing about JFTerm is it does the
colours so well... Erm... I think I'll just pop off and take those pills the
doctor gave me <grin>.


Supported Features
------------------
People always go on about the features their program has... I've got to do
this, just because they do :-)

* Full line editor (with complete history)
* Infinite history and display length
* ANSI colour support, including Dim, Reset and vague support for Underline and
  flashing colours (see later)
* Text can be pasted in from files
* Very pretty GUI (shame about the rest)
* Nice simple site editing window
* All the colours, even in 16 colour modes (thank the Lord for ColourTrans)
* History window
* Saving of text and selection supported
* Simple extension to program by use of libraries (IRC, Finger and Chat
  currently)
* Return is supported as 'delete current line' - this should allow you to use
  OakTree in dumb mode, but is by no means a complete solution
* Comprehensive scripting system should allow building of complete clients
  for talkers, etc...
* Extensible menus for different styles
* Support for adding daemons either initially or dynamically.
* URL launching (double click on the URL) using ANTs protocol
* URL reception (ANT or Acorn protocols), accepts x-irc: and finger: style
  URL's
* Partial line display, any lines only partially received will be shown in the
  display as much as they have got (useful on MUDs)
* IRC client supports :
    DCC Chat (with the Chat library)
    mIRC colours
    Johnathan Duddington's Speak module
    Bold, Underline and Inverse variants
    WimpCTCP protocol
    Descriptive mode changes and bans.
* Basic speak support for all windows
* Dragging in display makes selections, adjust to change selection.
* Fonts supported everywhere, variable whilst connected and configurable. 


Wishlist
--------
Yeah, and some people stick a wishlist of things they'd like to see... I
suppose I ought to too, but don't take this as any guarentee that I'll do
them - I'm busy atm :-(

* Triggers & idle events (you what ?)
* Use Zapredraw, to use any Zap font (update to DispLib at some point...)
* Efficient socket code (pah!)
* Telnet escape code support (if I can be bothered)
* Limited history and display length
* Ability to change fonts through a line (too much of a biggy really!)
* Being able to drag a file to a window to DCC it...
* Turning off background colours at the end of lines in IRC style.
* An empty wishlist


Colours
-------
The all 8 ANSI colours (primary and secondary) are supported, as are the
following :

 * Normal (resets all colours) (ESC[0m)
 * Bold (ESC[1m)
 * Dim (ESC[2m)
 * Reset (resets effects) (ESC[3m)
 * Underscore (ESC[4m)
 * Flashing (ESC[5m)
 * Inverse (ESC[7m)
 * Invisible (ESC[8m)

Underscore and flashing are emulated by changing the colours slightly -
you'll see what it's meant to be, but it doesn't look too amazing...

There is a bit of a problem with 'dim white' as this is almost completely
invisible, but... well, who cares - if anyone wants to use 'dim white' they
can just take a running jump...


Bugs
----
The scroll-back and history are infinite. If you talk for 5 days in a single
session you'd better have lots of memory because JFTerm doesn't forget
anything unless you close a connection (but seems to not have any leaks at
all then). Similarly, closing a window on a closed session which contains
lots of text (or clearing it) will usually result in a small delay. On a
StrongArm chats of 14 hours have taken around 30-40 seconds to close. This is
a heap problem really - recoding in assembler might help, but so might a
non-infinite scrollback.

    
Updates
-------
This program may (or may not) be updated periodically. By clicking on the
infobox window entries for Author and Version you can move directly to the
web pages for the Justin Fletcher and this application respectively.


Help and message files
----------------------
This application is fully !Help compliant and it is recommended that when
getting to grips with it the help should be used if only to give it some
purpose! It also supports the use of MessageTrans and therefore translation
to another language or changing the messages for the fun of it is much easier
than it might have been.


<BasicLibrary$File>
-------------------
This application requires Justin Fletcher's JFShared library to function.
This can be obtained from Arcade and possibly other bulletin boards. A
version is currently being carried by Hensa, but for the latest version you
would be best off looking at Justin's web page (see below), or contacting him
by one of the other means below. You can also request a copy of JFShared by
mailing Justin with the subject set to 'Send: jfshared' without the quotes.


Woo image
---------
As previously I've released the source for images I've used, I'm also
releasing the 'Woo' draw file. This (and more specifically the bubble around
it) may be used anywhere you like, so long as the bubble remains blue. Ok ?


Compatibility
-------------
This application has been tested on the author's machine (RO3.6), RO 3.7 and
RO3.1.


Disclaimer
----------
The author accepts no responsibility for any problems which this application
may cause or loss of data resulting in its use. This application is Public
Domain Freeware. This means that it may be distributed, so long as no charge
other than copying costs are charged for it. The copyright remains with
myself (Justin Fletcher).


Thanks
------
I'd like to say many thanks... Oh no... Just a few then :
  Angela Rayner, for testing and constructive critisism (will you use it
                 instead of FreeTerm though ? - and I've still not sorted that
                 great big menu - cut down your 'services' file :-) )
  Chris Johns, for spotting that JFTerm is just an engine for an IRC client
               and that that was what I'd intended all along
  Jogu, for constructive critisisms and encouragement
  Chocky, for similar critisisms
  Ducksnutz, for keeping me on the ball with the terminal and continually
             asking for selection support. Long after he stopped nagging, I've
             done it.
  Grendel, for additions to the IRC library
  Zappo, for help designing the WimpCTCP protocol and other fun ideas.
  Cliche for same.
  g0tai, for plugging JFTerm withoug meaning to :-)
  A few others on OakTree for more critisisms

And lastly, I'd like to dedicate this program to Helen Rayner; Just for being
wonderful...


Contact
-------
Any comments, queries, donations or bug reports can be sent to Justin
Fletcher at :

E-Mail : Gerph@innocent.com
URL    : http://users.essex.ac.uk:8000/
IRC    : On #Acorn as Gerph
Finger : finger jrflet@sunlab1.essex.ac.uk
Tel    : (01842) 813979

Snail Mail :
    Justin Fletcher
    Galadriel
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


History
-------
Version 1.00 : 06 Jun 1997
               First version written
               Basically this is a test-bed for DispLib and the embryonic
               PaneLib which is still held 'within' this application. As such,
               you can't really expect much of it.
               This is the first 'live' version - it went live a day before I
               heard of the existance of !Talker, so you can't say I was just
               trying to out-do them :-)
               This version incorporates multi-tasking connection, a little
               pop up box to ask where to connect to, and simple line
               colouring.
               Line handling is rudimentary. Much of the internals are fixed
               in this version. Beeps are not handled correctly and re-fire on
               every re-draw (unfortunately).
               Un-resolved hosts will /not/ give notification - this needs
               fixing.

Version 1.01 : 11 Jun 1997
               Fixed no-resolve bug (it wouldn't tell you the site doesn't
               exist!).
               Designed an icon (all of 5 minutes, as you can tell!).
               Wrote this !Help file.
               Decided I'm gonna need the nice Dynamic Menu handling library
               too... That makes a grand total of 5 libraries loaded and
               initialised on startup - a bit much maybe ? Beginning to
               wonder how I can be forced to use the External Edit library
               too, just because that'll be all the main libraries I've got !
               Astoundingly allows you to close connections too !

Version 1.02 : 11 Jun 1997
               Now allows you to close windows, find them and close the
               connections completely. Internal support for history added,
               Sites file added. I could probably use the External Edits to
               edit the sites file, but it's probably a bit of overkill
               really !
               Tiny weeny addition to make it have a line history (I mean,
               you wouldn't believe how small a change it was - only about
               20 lines and there's a history added - groovey :-); ok, so it
               took a few other changes to stop the pane attaching to it, but
               it wasn't much :-)

Version 1.03 : 12 Jun 1997
               Hey, you can save the text window now too... neat, huh ?
               Double clicking in the history window inserts the relevant
               line.
               Almost ready for a beta release I think :-)
               Oh, and it's stopped raining too... I can get some sleep now
               (I hope).
               Interactive help added.
               There's a memory leak somewhere in the code... About 300 byte/
               connection I think.
               Found the bugger... A few minor things I was forgetting to
               free when I closed a connection - in normal use there should
               be no leaks now.
               'something' is up... When I quit in two windows at the same
               time one of them sticks a ctrl-left into the sequence and
               tries writing quitquit for no good reason...
               Resizes the window correctly (a change to DispLib, adding
               Natural height of the window).
               BasCompressed - now takes 64k+page size for initial loading.

Version 1.04 : 12 Jun 1997
               Modified the sites file reading type - now the file is cached
               in memory, thus removing the need to read the file each time.
               This also allows a sites edit window. Sites edit window is
               navigable using keys and mouse, and always writes to disc on
               update. Added !Help stuff for new items on menu and window.
               Warns you if you quit when connections are pending. Quit
               window responds to keypresses now, but doesn't give back the
               focus - that's not really a problem I don't think...
               Designed a little sprite for the iconised version ;-)
               Help file needs updating...

Version 1.05 : 13 Jun 1997 (Release 1)
               Help file finally got updated (woo!) and made sure that
               'Delete site' actually works for a change...
               Made this a beta and packaged it up for release... Actually, I
               just wanted to stick a beta symbol on there for the fun of it,
               and I suppose it not being finished sort of influences it :-)

Version 1.06 : 23 Jun 1997
               Added 'libraries' for controlling different styles of
               connection; bit ropey at present, but getting better. Modified
               the sites file format to reflect this.

Version 1.07 : 30 Jun 1997 (Release 2)
               Minor internal modifications (inc. code \r fixed!). Wrote the
               basics of the IRC library.
               BasCompressed with a number of changes required to the Special
               file.
               IRC library handles simple things :
                 /join <channel>
                 /part
                 <text>                  (for messages)
                 /me                     (for actions)
                 /ctcp <nick> <things>
                 /ping <nick>
                 /quit <message>
                 /mode <options>         (with intelligent sentance generation)
               And nothing much else !
               Updated this help text a litte... It really needs re-writing.

Version 1.08 : 03 Jul 1997
               Massively updated IRC library - now handles joining channels
               correctly - a few updates to IRServer have been required too.

Version 1.09 : 03 Jul 1997
               Added keypress handling code to !RunImage, modified irc
               library and the finger library to supply default functions.
               IRC library has rudimentary tab cycling stuff - could possibly
               be changed to handle tab completion, but I'm not there yet !

Version 1.10 : 13 Jul 1997 (Release 3)
               Added extensible menus for styles (and moved the description
               from 'wishlist' to 'features' :-) ). Added 'how to write styles'
               section.
               Fixed QUIT bug in IRC style.
               Added bold, underline and inverse support to IRC style. A few
               minor bug fixes added.

Version 1.11 : 18 Sep 1997 (Release 4)
               Added 'dynamic daemons' and wrote Chat style to test this.
               Redesigned the internal structure of the styles so that we can
               now have some 'global' workspace. I may even have to add
               configuration windows soon - now there's a scarey thought :-)
               Added library menu to the info window. Should allow selection
               of colours and other configuration type things (menu's only
               at present).
               !Help updated to take account of new flags. Chat now has a
               library menu (available from the 'Libraries...' window).
               Currently Chat is an example of libmenu's, and IRC an example
               of connection menus and key handling.

Version 1.12 : 30 Sep 1997
               Added inter-style communication via FNcalluser to allow IRC to
               now have a DCC Chat connection if the chat library is
               installed. Removed all control characters (except 27) from the
               display line. Chat library now has an interface for external
               connections from other libraries.
               URL launching added and fixed bug in history window to allow
               double clicks.
               URL reception added and fixed bug in 'Connection refused' code.

Version 1.13 : 04 Oct 1997 (release 5)
               Many changes to allow connections to be passed parameters (and
               thus allowing x-irc://<nick>@<host>/ to work (!). Finger client
               improved to support URL's now. Internal functions for calling
               libraries all changed to be subsets of FNcalllibslow allowing
               more complex masks to be set up. Library functions changed
               to be more consistant (global parameter is now /always/ first
               regardless of the context). As a consequence, DCC Chat should
               now take the name of the user and use that in 'ACTION'
               requests.

Version 1.14 : 10 Oct 1997
               Added ServerName (now HostName) code to set JFTerm$HostName -
               thanks to Dave Thomas for letting me do this. Improved the
               URL handler to cope with the indirected URLs. Proxy capabilities
               added; currently set up for JFProxy, but should be simple to
               modify the proxy library to handle other proxying systems. All
               connections are made via the proxy, but incoming connections
               are /not/ catered for yet; whilst I've lots of ideas as to how
               this might be made possible, the logisitics behind them makes
               them prohibitively difficult :-(
               Fixed disconnect message code broken in v1.13.
               IRC library now finds it's local hostname so that it can connect
               to elsewhere.
               Proxying made more stable and removed possible 'close
               connection' whilst negotiating with proxy problems, and similar
               script calling potential problems by setting ConnectProxy as the
               state.
               Clearing windows should be more stable now.

Version 1.15 : 31 Oct 1997 (this version intended for me to use at the show!)
               Added bans list decoding. 
               (Hopefully) an extension to allow 'long' lines to be displayed
               without ??? at the front.
               Away added. 
               Bug in topic fixed (used to ignore long lines).
               Bans added.
               Added new URL for this application,
               http://clients.undernet.org/acorn/JFTerm :-)
               Minor buglets fixed.

Version 1.16 : 19 Dec 1997
               Added partial line display; rudimentary, but sufficient I feel.
               Partial display is only really relevant to a minority or user
               protocols; of these Chat and Default both support this.
               Colouring in partial lines is /NOT/ supported at present.
               Fixes for minor bugs in IRC (msg/me/notice).
               Line Wrapping (rudimentary).
               Multi-character replacement (!, *, #) by two.
               Beeps finally restored to working order.
               Double-clicks on URLs with brackets will work, as will those
               with URL:<url> as recommended by URI RFC (IIRC).
               Additions by Grendel to IRC; Ignore lists, mIRC colours, key
               sequences (ctrl-b,i,u,g); changes to SetInput.

Version 1.17 : 21 Dec 1997
               Supports CTCP protocol as a test bed. Many changes to make this
               work. /send <nick> <file> might just work now, but you'll just
               have to take your chances - remember you need !DCC.
               Multi-character replacement now in assembler and works on any
               repeated sequence.
               Speak support added, and now made use a menu to select who
               speaks. Minor bug fixes and tweaks.
               BasCompress'd for the hell of it. Not fully optimal, but it
               should work. Now takes a wimpslot of 192k when run. If you want
               to use the uncompressed version you'll have to uncomment the
               lines in the !Run file otherwise it just will not load the
               libraries.
               Released to Spanners, CMJ, Angela Rayner and Ducksnutz.

Version 1.18 : 16 Mar 1998
               Speak support added to main program and available in all
               windows.
               Misc minor bug fixes.

Version 1.19 : 07 Apr 1998
               Saving made much easier (from programming point of view).
               Selections work. Clear selection added to menu, save box
               has 'Selection' option.

Version 1.20 : 12 Apr 1998-?
               Colours now work and are configurable. This is only
               implemented in the IRC script at present.
               Fonts implemented. Need I say more ?
               Beta 2 release: fixed bug in !Run file to allocate more
               memory. Fixed upgrade path when not upgrading (!).
               Beta 3 release: Edit menu improved - added select all, and
               copy to clipboard. Clipboard supported for export only.
               Release Entity supported. Most of the code for this is in
               DispLib. This means that /any/ DispLib client suddenly
               is now fonts capable, selection capable and may use the
               clipboard. Only JFTerm exploits this at present.
               Added UMode to the IRC library, began documenting the commands
               that IRC supports.
               URI protocol now accepts Acorn style URI's - x-irc is back
               working with Browse ! Finger also works now too.
               Miscellaneous changes to the parsing system.
               Icon added to the info box, (!help icon) to bring up the !Help
               file. Added keyword masking (killwords).
               Added panes option to modules. These are still experimental.
               IRC style uses this to provide a couple of buttons at present.
               Chocky obviously really wants this. Enable it using the
               libraries options menu.
               Released in various beta states to Freenet.
               Multiple pane closure bug fixed - shouldn't give exceptions if
               you disconnect now.
               IRC style now supports ECHO CTCP (oops!)
               Bug found when joining channel with lots of names. Oh dear.


Version 1.21 : 09 Jun 1998
               Decided that I need a base version number to work from. Most of
               the program is fundamentally 1.208, but some minor updates have
               been added. IRC style now has nicer tabbing (tab now changes /me
               as well as /msg).

Version 1.22 : 11 Jun 1998
               Kinda boffed that last version. Looks like this one will be
               much more stable.
               URL launching now fixed. URLs with dupes in will be left as
               seen, hopefully. You can always turn off dupe removal if you
               dislike it. Register itself with Speak when it is first used,
               will attempt to load speak when started and if we've used it
               during this session, deregisters us on quit.
