Nettle - Telnet and terminal emulation for RISC OS
==================================================

Version : 0.202x : February 21st, 2002.  (BETA DEVELOPMENT VERSION)

Nettle is *the* terminal emulator and telnet client for the RISC OS
operating system. It utilises the ZapRedraw module for speedy display and
is a fast, clean native implementation.

Nettle's aim is to be the definitive terminal emulator and telnet client
for RISC OS.  A range of terminal emulation options will be supported,
along with full colour and graphics.  An ANSI task window is provided, so
that ports of unix programs which provide ANSI output can be run on RISC
OS in full colour and form.  (Programs such as ncftp2, BitchX, nano, lynx).
Other highlights include an optional line editor with history, hotlisting,
multiple terminal support and URL launching.  Eventually, Nettle will also
contain Secure Shell (SSH) support.


Requirements
============

Nettle uses the ZapRedraw module for display.  If !Zap or !ZapFonts have
been "seen" on your system (often by virtue of having !ZapFonts in the
!Boot.Resources directory) then you will have a wide variety of fonts
to choose from within Nettle.  If Nettle cannot find any fonts, then it
will fall back to using two contained inside its own structure.

Nettle currently requires Wimp 3.50 or better.  All versions of RISC OS
can have at least Wimp 3.98 ("Nested Wimp") loaded, however, users of
RISC OS 3.1 may not have this installed and see some reduction in
functionality.  This will be addressed in a future release where we
intend to directly support older WIMP versions.

In common with other RISC OS internet access software, to connect to
other machines, either !Internet or !FreeNet must be operational on your
computer.  The Acorn/ANT 'Resolver' module is also required. Nettle also
makes use of the "SocketWatch" module for improved performance - an
installer is provided.   Note that if you only wish to use the ANSI
task window facilities of Nettle, then Internet/FreeNet is not required.

Finally, Nettle makes use of the ColourPicker module.  This must be
present in your !System folder.


"Dummies guide" to using Nettle
===============================

Unpack !Nettle to your harddrive and doubleclick on it - an icon will
appear on the right hand side of your iconbar.  Clicking SELECT on this
icon will open the connection window.  Enter an internet host name in
to the "Host" icon, optionally supplying a port number after a colon.
Click to "Connect" button and a connection will be attempted - a larger
terminal window will appear, showing connection status.  If all goes
will, you will be able to use the service you requested.   Once finished,
simply close the window.


Using Nettle
============

Creating connections

Clicking on the Nettle iconbar icon will display the connection dialog.
From here you may choose the connection type (Telnet/SSH/ANSI task)
and terminal emulation desired (vt100/vt102/vt220/xterm).  The hostname
and port ("host.name:port") can be entered below for telnet and ssh
connections.  For ssh and ANSI Task connections, the command icon will
be available to supply a default command to run (eg "bash").


Using the terminal

Once a connection is made, the terminal can be used as normal.  If a
line editor has been enabled (the initial default is "off") then the
input will be line-buffered locally and up/down cursors will scroll
through a history.  This may be undesirable for interactive programs
running via the terminal or for password entry.  Nettle will print a
message in the window when the session has ended.

During use of the terminal, the mouse can be used to select areas of
text in the usual RISC OS manner.  An application menu (click the
middle mouse button in the terminal window) will allow the selection
to be cleared, transmitted via the terminal, or saved to disc in either
plain text or full ANSI format.   The menu also gives access to a resize
dialog allowing the terminal size and scrollback to be changed.

Note that when remote mousing is in operation (eg when running "pico -m")
then local mouse operations will not function - selection and the session
menu will be unavailable.


Tailoring Nettle's defaults

The default terminal size, font, colours, scrollback size and so on can
all be modified from within Nettle:  Choose the "Choices..." option from
Nettle's iconbar menu and the main Choices window will appear.  Choices
are split in to several categories (Size/Colour/Hotlist...) and clicking
on the radio buttons at the top right will display choices for that
category.  Update the choices as you desire, then click "Set" to set
them for the current run only, or click "Save" to save them as defaults
which are reloaded the next time Nettle is run.


Hotlist

Nettle has a hotlist feature, similar to most web browsers.  Sites that
you connect to regularly, and terminal settings for those sites, can be
defined as a hotlist item and saved to disc for quick access.  The
hotlist editor can be seen by selecting the "hotlist" option in Nettle's
choices window.  From here a new hotlist item can be created, existing
items may be edited or deleted, and the list can be reordered by dragging
items around.  To select an item for edit/delete/copy, just click on it.
Dragging items will allow the list to be reordered to suit usage.
Doubleclicking will go straight in to the item edit mode.  The hotlist
is saved to disc when you select "Save" from the Choices window and
loaded when Nettle is loaded.  You can access the hotlist by clicking
ADJUST on the Nettle iconbar icon or from the "Hotlist" iconbar submenu.


Main window

All input to nettle is via the main connection windows of course.  If
a line editor has been enabled, then it will appear as a pane hanging
below the window.  Enter text in here as usual and hit ENTER to send it.
The line editor has a "history" - use up and down cursor keys to access
recently entered commands.   This line editor is useful for slow
connections - eg telnet over a modem or to a distant site.  If the line
editor type has been set to "Optional" then there will be a checkbox to
the right of the window to allow it to be temporarily disbled (eg when
you need raw mode input, or want to enter a password).  If the line
editor is set to "Permanent" then the line editor window will always be
active, but clicking in the window will allow raw input - this is akin
to the behaviour of apps such as ANTTerm.   Try each option and see which
suits you best.

You can mark a selection of text in the main window in the usual RISC OS
manner.  This selection can then be saved by simply dragging it to a filer
window or another app.  Clicking menu will open the terminal menu where
you can follow the "Selection ->" item and save via a standard save dialog.
This also allows you to save out the full ANSI control code info too.
The application menu also allows you to send the marked area back to the
terminal.

Nettle can launch URLs for you.  Doubleclicking on any word in a terminal
window will attempt to launch a RISC OS web browser for that text.  Nettle
supports all common URL launching mechanisms (Fresco/Oregano/Browse).

Nettle supports the global clipboard via entries on the session menu and
files can be dragged to a session window to transmit their contents.

For systems that output ANSI graphics characters, you may intially see
"top bit" characters (with accents) drawn.  You should switch to a font
which draws these as block graphics - eg "08x16.PC" font.  This is seen
when connecting to ArcadeBBS for example.


ANSI task
=========

Nettle provides a ANSI task, primarily to allow ported Unix programs
which have ANSI output to be run on RISC OS.  The task window operates
slightly differently from other task window implementations (eg Zap/Edit)
to allow for this ANSI emulation.  Don't expect to run "normal" interactive
RISC OS programs in here (e.g. BASIC, gos) because they will not function
in the way you expect - ANSI terminal control is quite different to
RISC OS.   Programs which are intended to be run via Nettle's ANSI Task
include nano (pico), tinyfuge, lynx, BitchX, ncftp2 and so on.  Nettle
is the only RISC OS program that we know of that provides this kind of
functionality and allows these unix ports to be run at their best.


Project background
==================

Alex Macfarlane Smith started the project, initially writing a very well
featured version of Nettle in BBC BASIC. Unfortunately, this was rather
too slow to be really useful, so after some encouragement, the move was
made to a C-language based development. This is when the other developers
started work. 

Nettle currently supports vt100, vt102, vt220 and xterm terminal
emulation. This is now fairly fully fledged and working well - support
for other common terminal standards (vt320, vt52) is planned for later. 

For various reasons, Nettle can be built on RISC OS (with gcc / Norcroft)
and on Linux, with gcc. Either UnixLib or the standard shared C library
can be used! None of this makes much odds to the workings of Nettle, but
provides a nice variety of choice for build environment. (Nightly Linux-
based snapshot builds will be undertaken soon). Current releases are
built in traditional fashion with "Norcroft" CC and Shared C Library
stubs, due to stability problems with gcc's output. 

Opensource development is managed via SourceForge - feel free to submit
patches and bug reports via that system: http://nettle.sourceforge.net/
Report bugs and enhancements to mailto:archifishal@users.sourceforge.net


Main developers (sourceforge id)
================================

Alex Macfarlane Smith ("archifishal") - project lead / telnet guru
Peter Naulls ("pnaulls")              - unixlib/gcc specialist
Ian Jeffray ("ijeffray")              - gui/ui/wimp/stubs
Joseph Heenan ("jogu")                - url/general os expert

Contributions, assistance and patches have also been received from
David Thomas, Darren Salt and Justin Fletcher.


"To do" list - forthcoming features and ideas
=============================================

This release of Nettle is by no means complete, but we decided it was
time to release a binary version, as it's quite stable and very useful
as it stands.  Here's a roughly ordered list of things that will be
added in future versions.  Please feel free to submit new ideas:
mailto:archifishal@users.sourceforge.net

* ANSI commandline task shell for ANSI task window (ROSH)
* Scroll to bottom on keypress
* VT 320/420/510
* rlogin
* SSH


Known issues / bugs
===================

If you find a bug that isn't related to the list of unfinished items
above, and isn't a known bug shown below, please let us know:
mailto:archifishal@users.sourceforge.net

* Terminal emulation incomplete - esoteric vt commands unimplemented
* ANSI task cannot be used as a "regular" taskwindow.
  - It never will, because it interprets codes as ANSI - that's its
    whole point in life.  This will be improved by "ROSH"


Release History
===============

0.1306b : 1999 - 2001
    Initial BASIC versions

0.2000r : September 1st, 2001
    Features:
      Recoded in C
      Supports vt100, vt102, vt220, xterm emulations
      Telnet and ANSI task connections
      URL launching

0.2010r : September 16th 2001
    New features:
      Remote mouse support (pico -m, mc, links etc work nicely now)
      Support basic telnet://hostname/ URL launching  (no user/password yet)
      Inverse video emulation
      Session spooling (logging)
      Support X11 DISPLAY passing to remote
      Implemented save/resore cursors
      Support for blinking characters
      Accept telnet requests to suppress go ahead
      Global clipboard support
      File loading (dragging of files to session window)

    Changes/Improvements:
      80/132 column switching doesn't change width on terminal reset now
      Better support ANT broadcast launching of URLs
      Improved recognition of URLs under double-click in terminal window
      Builds with new unixlib file structure
      Runs templheadr from a specified location
      Change menu wording ("Connect..." is now "New Session...")
      Much faster terminal drawing
      Hotlist editor gains "Copy" button - buttons grey-out at appropriate times
      Hotlist redraw cleaned up and made less flickery
      Hotlist items can now be dragged around to change the ordering
      Improve region scrolling behaviour

    Bugs fixed:
      Correctly turn off local echo (telnet to ArcadeBBS now works properly)
      Corrected hotlist editor tab ordering
      Hotlist editor couldn't create command for ANSItask
      Terminal speed reporting (and change reported speed to 38400)
      Selection saving fixes
      LINES/COLUMNS variables now correct (for use by ANSItask apps)
      Rare stack corruption solved
      Could sometimes continually swap cursor between two windows
      DNS lookup corrected

0.2020r : February 20th, 2002
    New features:
      Iconised window naming
      Cope with and translate control characters when pasting
      Warn about open sessions on quit/shutdown
      Paste URL/URI files rather than launching them
      New choices section for 'miscellaneous' options (eg blinking)
      Versioned choices files
      Mouse support for Shift/Ctrl/Alt combinations
      Dynamic resizing of window -- optionally only when CTRL is held
      Accept user:pass@host format as a host entry for auto logon
      Handling of "telnet:user:pass@host:port" URL format
      Two types of terminal cursor : block or underline.
      Character underline support
      Display terminal size in scrollbar when dynamically resizing
    
    Changes/Improvements:
      Multitasking speed when pasting large amounts
      Optional line editor can now default to 'off'
      Don't unnecessarily add blank spaces to end of lines
      Allow pasting of HTML, ask user when pasting other types
      RISC OS 3.5+ style error categories
      Positioning of new terminal windows is more standardised
      Better cursor drawing and display of 'ghost' cursor
      Large memory savings -- smarter use of ZapRedraw
      Terminal reset
      Handle 'stop bold' command and use it in ANSI saving output
    
    Bugs fixed:
      7bit/8bit VT escape sequences corrected
      Selection of rows when dragging selection a long way out of window
      Resizing on a mode change correctly
      Position cursor correctly when terminal resizes
      Hold on to selected area correctly when terminal resizes
      Fixed crashing on font change
      Ensure ZapRedraw at least 0.39 as we don't like earlier versions
      Double-clicking on IPs now does what you'd expect it to
      Swap top T bottom T around
      Corrected shutdown sequence so that desktop can be shutdown cleanly
      Some reasonably large internal cleanup and restructuring
      Read size of toolsprites from WIMP -- correctly position line editor
      Save as ANSI inserts proper ANSI sequences!


(C) Nettle developers, February 20th, 2002.

