RetroZilla/extensions/xmlterm/INSTALL

INSTALL: Installation instructions for XMLterm source code
----------------------------------------------------------

*NOTE* This is work in progress. User beware!

*NOTE* Check the XMLterm web site <http://xmlterm.org> for updates.

15 Mar 2000

QUICK BUILD INSTRUCTIONS (Linux/Solaris)
----------------------------------------
If you have already built mozilla from the source, then type the following
commands in the "mozilla" directory to build XMLterm:

a) configure --with-extensions=xmlterm <other-configure-options>
b) cd extensions/xmlterm
c) make

[Skip step (b) for a fresh build of mozilla from the source tarball]

To execute XMLterm, type one of the following commands in
the mozilla/dist/bin directory:

   ./xmlterm
  OR
   ./mozilla -chrome chrome://xmlterm/content/xmlterm.xul


DETAILED BUILD INSTRUCTIONS
---------------------------

In the following discussion, file and directory names are relative
to the main ("mozilla/extensions/xmlterm") directory. See the end of the
README file for a brief description of the subdirectories.

1. Source tree (skip this step if XMLterm is already in the source tree)
------------------------------------------------------------------------

The XMLterm source code is distributed as a tarball "xmlterm.tar.gz"

This tar file needs to be untarred in the "mozilla/extensions" directory.
A subdirectory called "xmlterm" will be created there.
("mozilla" denotes the root directory of the Mozilla source tree)

If you have already untarred it elsewhere, simply move the "xmlterm" directory
to the right place.


2. Configuration
----------------

To recursively create all Makefiles from Makefile.in files, type the following
in the "xmlterm" directory:

config/makemake -r

The file "config/xmlterm_config.mk" contains XMLterm specific configuration
information that is needed in addition to any Mozilla configuration
information. It has already been hand-configured for Linux2.0/Linux2.2, and
Solaris2.6 platforms. It may need to be modified slightly to compile XMLterm
on other platforms.

At present, XMLterm has been tested only on Linux (RedHat6.0) and Solaris2.6
platforms, using the M11 release as the base version of Mozilla.

XMLterm typically uses the UNIX pseudo-TTY interface to communicate with the
shell. This interface is implemented only for Linux and Solaris platforms at
the moment.

XMLterm may compile on other Unix platforms, but it will use NSPR pipes,
rather than a pseudo-TTY, for process communication; this means that the
terminal control characters, such as Control-C for interrupting jobs, will not
work on those platforms. (See the file doc/PORTABILITY for a discussion of
portability issues)


3. Creating the dynamically loaded XPCOM/XPCONNECT component
------------------------------------------------------------

To create the dynamically loaded XPCOM library, type the following in the
"xmlterm" directory:

  make all

This creates the self-registering library "libxmlterm.so" and installs it in
the "mozilla/dist/bin/components" directory, along with some chrome
files. After this step, the following interfaces become accessible in Mozilla
through XPCOM/XPCONNECT:

  mozIXMLTermShell     (interface to XMLterm)
  mozILineTerm         (interface to the stand-alone LINETERM)

To clean up completely, type

  make clean


4. Running XMLterm using mozilla
--------------------------------

At this time, XMLterm cannot be accessed through the menu bar. After Step 3,
execute the following command in the "mozilla/dist/bin" directory:

   ./xmlterm

"xmlterm" is shorthand for the following command, which you may also execute
directly

   ./mozilla -chrome chrome://xmlterm/content/xmlterm.xul

The above command(s) should create an XMLterm window. Click on that window
with the mouse to give it focus and start typing UNIX commands.

**NOTE**
The command prompt is assumed to be terminated by one of the characters
"#$%>?", followed by a space. If this is not the case, many features will
not work. This restriction will be relaxed in the future.

The command line can be edited using EMACS-style key bindings.
Command completion should also work with TCSH and BASH, as should history
recall.

By default, blue coloring is used to indicate clickable display elements.
Note that the prompt and the input command line are clickable.
(Of course, the appearance of XMLterm is completely configurable
using the CSS stylesheet chrome://xmlterm/skin/default/xmltpage.css)

After typing one or two commands, click on the prompt string of any
previous command to see what happens! Then click again on the same
prompt string.  Also click on "Hide all output" button at the top of the
document.

Double-clicking is used to activate all XMLterm features, *except* for
command prompts and underlined hyperlinks, which are activated by a single
click as in a browser.

Double-clicking on a previous command line (to the right of the prompt)
re-executes the command. Be warned that double-clicking a command line can
profoundly affect your computing environment, depending upon what the command
is.

The sample Perl script "xls", the iconic/hypertext version of the Unix "ls"
command, is in the "scripts" directory. Also in the "scripts" directory
is "xcat", an XMLterm-aware version of the "cat" command.


5. Setting the path
-------------------

To use XMLterm most efficiently, add the mozilla binary directory
(mozilla/dist/bin) to your execution PATH variable by modifying
your shell initialization file (.profile/.cshrc). This will enable you to use
commands such as "xmlterm", "xls", and "xcat" easily.


6. Stand-alone mode (optional)
------------------------------

Although XMLterm resides in the Mozilla source tree, portions of it are
capable of being compiled and linked completely independent of Mozilla. You
may want to do this for testing purposes. The "config" directory contains
make files that are used for this stand-alone mode. There is even a dumb
script called "makemake" which can be used to re-create make files, if the
corresponding Makefile.in files have been changed.

*NOTE* The executable "lterm" requires the NCURSES include file "curses.h"

To create the stand-alone executables, type

 make STAND_ALONE=1 all

(To clean up stand-alone modules, type "make STAND_ALONE=1 clean")

This creates the stand-alone library in "base/lib" and some stand-alone
executables in the "linetest/lib" directory, in particular, one called 
"lterm".

The executable "lterm" implements a line terminal (LINETERM), i.e., a
non-graphical version of XMLterm. In the future, this may be implemented using
NCURSES for full screen operation. At present, it only provides line-at-a-time
functionality and is used only for testing.

LINETERM acts as an "engine" for XMLterm, carrying out all the non-graphical
tasks, completely independent of Mozilla. It is written in C and is licensed
under both MPL and GPL. It provides functionality similar to the EMACS shell
mode or the GNU readline package.

LINETERM has various options where trace output may be redirected to a
different TTY device, for debugging purposes. LINETERM may be used like the
shell command "sh", e.g.,

  prompt% lterm
  prompt% ls
         <listing>
  prompt% exit

The "tests/escape" program can be used to generate terminal escape sequences
to test the XMLterm API. In particular, the following command enables
extensive trace output, if executed within an XMLterm or LINETERM:

  tests/escape 1 98 D

-----------------------------------------------------------------------------