Welcome -*- text -*- :-> to the FW-macro package for THE, the Hessling Editor

WHAT IT IS
----------
The FW-macro package is intended to implement a higher functionality
level to THE via REXX, and to show, what is possible to do with this
editor. As I'm working primary with OS/2, the things refer to this
situation. If the package can be used on other systems, let me know
(there is a first report on using it with linux). Just check it
out. Or even better, try to port it...

The main features of this package are:

o resemblance to WordStar/turbo-Pascal key mapping, look styles for XEDIT,
  KEDIT, THE also supported

o resemblance to WordStar/turbo-Pascal funtionality (enter, block
  marking, cursor movement), even when in compatibility mode to THE,
  KEDIT, XEDIT.

o menu capability, shown for the use with TeX (makes THE to a
  TeX-shell, from where the compilation/preview/print etc. in separate
  tasks can be controlled). Dynamically changing menu pages and free 
  cross references between menu pages are possible. Operating system
  commands could be put there too.

o selectable help, keyword lookup in .INF-files (for REXX and
  TeX-files, others can be implemented)

o large set of macros for quickly inserting TeX commands and
  structures (kindly provided by Agustin Martin Domingo)

o extended use of the DIR-file (sorting, stack name to cmdline,
  extension sensitive execution of commands...)

o systematic keybindings for handling block marks (most with
  shifted function keys)

o undelete buffer for block mark 

o paste buffer (clipboard) for collecting text portions

o simple key bound handling of the files in the ring, query detailed
  status of ring, simple pick and go of a file

o start THE with -atarget to begin editing at the target position

o pick list storing the last session, you can (automatically) reload
  all last edited files to the ring and restore edit positions and
  bookmarks ('points') set 

o added macros like 'extension', 'format', 'inserttext', 'locring',
  'o', 'qlocal', 'qthisline', 'stackword', 'allx'...

o function key paper mask to be processed with LaTeX

The resemblance to WordStar/turbo-Pascal can only be partial.
Let me know about inconsistencies and other strangenesses.


WHAT YOU NEED
-------------
o a THE version as new as 2.5beta (Nov 16th 1997)
o a REXX-system  (OS/2: with rexx.inf for keyword-lookup, on unix
  Regina won't work properly :-(, so use REXX/imc instead)
o a file system with the capability of long filenames
o Info-Zip's Unzip 5.0 or equivalent to unzip this archive
o some free space on disk (about 1MB) for the files and some time to spend
* optional: (em)TeX-system (OS/2: with latex.inf for keyword-lookup)
* optional: lynx/netscape... to view THE-manual in html format
* optional: 'etags' and 'find' to create tags file for THE-macros
* optional: 'ls', 'grep' for allx.the
* optional: 'recode' for TeX-system
* optional: 'complete.the' from Pablo Garcia-Abia ('ls' recommended too)


DISCLAIMER & COPYRIGHT
----------------------
The FW-macros are protected by copyright (C) 1994-1996 to Franz-Josef
Wirtz, except the set of tex\am*.the-macros, which are copyrighted to
Agustin Martin Domingo.

The whole macro- and batch-package with all its files 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 any later version.

All these macros, batches, menu- and helpfiles from the package are
distributed in the hope that they 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 macro; if not, write to:

   The Free Software Foundation, Inc.
   675 Mass Ave,
   Cambridge, MA 02139 USA.


INSTALLATION
------------
0) Before you start you should make a backup of any previous
   installations to save your changes. When you start trying edit
   sessions with FW-macros in effect, you should not use critical
   files in first place, but some test files, until you are familiar 
   with the concepts of FW-macros. It's likely that you say 'oops,
   what happened?' ;-) So be warned. 
   If you're used to plain THE/KEDIT/XEDIT you probably should choose the
   appropriate compatibility mode instead of FW-mode (see below).
   Although even then it's *not* exact compatibilty, it's at least
   closer to what you already know. If you want to get it more closer,
   you can disable distinct "features" introduced by FW-macros (see
   below).

1) Install THE as described there, i.e. setup the environment variables
   THE_HOME_DIR and THE_MACRO_PATH. Be sure to install the documents
   too (THE_Help.txt, the.man and *.htm, demo.txt).
   Install other macros or macro packages as described there
   (e.g. AM-Latex macros).

2) Choose a directory to unpack the FW-macro package (i.e.
   'g:\home\fjw\fw', '~/fw', 'c:\Programs\freeware\THE\contrib\fw' or
   something alike) and unpack there. This directory *doesn't* need to
   be in the PATH statement (but it does no harm if it is
   ;-). Instead, place the batch 'fw.cmd' ('fw.bat', 'fw.sh')
   to a directory searched by your PATH (unix: or make a link to
   it).
   Note: The other batches/scripts in the subdirectories (like tex\c.cmd)
   *should not* be moved!

3) In case you want to use different THE-configurations (your favorite
   one, plain THE and FW-macros...), you can use the batch 'fw.cmd'
   ('fw.sh', 'fw.bat') to start an edit session, which leaves the
   current THE-configuration untouched. This way you can use pure THE
   by typing 'the' at your command prompt in the usual way, and THE
   together with FW-macros by typing 'fw'.

   In case, you want to use *always* THE together with FW-macros in 
   effect, you could alternativly setup the environment variables for 
   example as follows within your 'config.sys', '.bashrc' or
   'autoexec.bat'. When you do so, you are not able to run *pure* THE
   anymore, unless you unset/reset the environment variables
   accordingly.

   ** Using one of the fw-scripts is always the safest decision. Then
   ** you don't have to worry about any env-variables, profiles or so.

   The following variables control the behaviour of THE/FW-macros:
   THE_HOME_DIR=f:\usr\THE
   THE_HELP_FILE=f:\home\fjw\fw\mainhelp.mnu
   THE_PROFILE_FILE=f:\home\fjw\fw\fw.the
   THE_MACRO_PATH=.;f:\home\fjw\fw;f:\home\fjw\fw\tex;f:\home\fjw\fw\the;
                  (ctd.) f:\home\fjw\fw\cmd;f:\home\fjw\fw\std;
                  (ctd.) f:\usr\THE\contrib;f:\usr\THE

   Note: Either 'fw.cmd', 'the.exe' or an own batch should be in a
   directory listed in your PATH statement to use it in any command
   shell. You surely can also make an assignment in their notebook to
   'plain text' files (OS/2), or create an object (OS/2)...

   Note: Before you can use 'fw.sh' on unix you have to make the file
   executable ('chmod u+x fw.sh' or something similar).

   Now: change to the directory you unpacked all the FW-files and run the
   appropiate starting script ('fw.cmd', 'fw.bat' or 'fw.sh'). The
   first time, this script is called, it calles an initialization
   macro to query some infos for setting up the system. That's where
   you can choose, how FW-macros should behave (which compatibility
   mode is in effect) and which features should be enabled or disabled.

   The retrieved informations are saved in two files within your
   HOME-directory (names vary depending on operating system). These
   two files are used in any later edit sessions you start. You can
   call the initialization macro 'fwmkrc' in later session again, or
   edit the two files directly, if you like.

   After these files have been created, THE terminates and restarts
   with the chosen setup. Now you're ready to run. You can also quit
   now and change to the desired directory and start your work or
   tests there. Only for initialization purposes you're restricted to
   run the fw-scripts from the install-dir.

4) This step is only necessary, if you may want to use the TeX-system
   (currently only useful on OS/2).

   Check, wether the 'tex\*.cmd' files reflect your TeX-implementation
   and make the changes necessary. Especially look for the commands to
   invoke the TeX-compiler etc. Usually you should have batches like
   'latex.cmd' somewhere in your EmTeX-tree or local bin directories.

   Have a look to 'tex\env.cmd' to see, how it works on my OS/2-system
   with EmTeX (Note: this file is changed by the FW-macros menu
   system). In case you want to access various logfiles, look at
   'tex\log.the' and adjust it to your dvidrv-configs (or vice versa).

   You might want to add a line like

   SET EMTEXED=@THE -A:%1 %2

   to your config.sys or startup batch to make use of the facility for
   editing the TeX-file (%2) at the error position at line (%1), in
   case you use your TeX-system via operating system command line, not via
   THE&FW-macros. Then your latex-batches should have been created in
   a way to react upon this situation. See the emtex-documentation for
   details. 

   Note: This is not necessary, if you control the TeXing
   from within THE. Then, the latex-batches should *NOT* react to an
   call for edit by themselves.

5) Here we are:-), just start editing. Try F10 for help (F1 if you 
   use XEDIT-compatibility or alike...). Try A-PGUP (C-HOME in
   XEDIT-style) in TeX-files to open the menu system. Use ESC (HOME in
   XEDIT-style) for switching between text and command line and C-K C-X
   (C-F3 in XEDIT-style) for exiting with the pick file feature.

   If you have a TeX-System, you're encouraged to process the file
   'fw_mask.tex' to get a paper mask with the key bindings to lay around
   your function keys. It works with latex 2.09 and latex 2e. 

6) After using THE&FW-macros for a while, you may want to make own
   extensions. So, feel free to extend ???\use???.the files to your
   needs. See the file extmnu.hlp for the general concept and the
   steps to do, then edit 'extension.the' and the templates in the 
   directories 'std' and 'tex'.

7) Adopt extension depending program calls in 'key_enter.the' to your
   needs.

8) Write comments and questions to me, invent new macros, menus, help
   files...., read the docs for corrections etc. Feel free to contact
   me. Send a postcard of your hometown, a picture from you, some
   lyrics... 


TRAPS AND HINTS
---------------
There are two environment variables which may affect FW-macros:
HOME and TMP. These variables, if set, *should not* contain the '~' as
a replacement for say '/home/fjw'. If these variables are not set, the
current dir is used. The HOME-variable is especially used for storing
the initialization files, and therefor, it is recommended, to set HOME. The
TMP-variable is used for storing files used during the work of
FW-macros, especially undelete buffers or infos about the ring.

The initialization macro 'fwmkrc' uses a mechanism to allow the
FW-macros to recognize which of the FW-packages are installed (by
checking for the corresponding README.xxx). If you don't want a
specific 'feature' although it's installed, just remove the
corresponding keyword from the list at FW_FEATURE within 'fwrc.the' in
your HOME-dir. If you have the 'complete.the' from Pablo Garcia-Abia you
can use the COMPLETE feature. If you have installed the AM-Latex-macro
package from Agustin Martin Domingo, you can use the AMLATEX
feature. If not, you should drop the corresponding items from
FW_FEATURES.

If you find UP/DOWN arrows working too slow, try C-UP/DOWN arrows
or the original wordstar-keys C-X and C-E.

If you start THE with no parameter, the current DIR may be shown. In
case, there is a 'pick.the' from a previous edit session, the files
specified there are loaded at that time, but _eventually_ you have to
leave the DIR shown anyway yourself (with ESC) to see the first file
loaded automatically.

It is recommended to leave all control- (alt- in the/kedit/xedit-
compatibility) and function-key assignments untouched. So you won't
break the FW inherent key-definition concept and no conflict should
arise on implementing a new version of FW-macros. Usually
user-assignments should use the ALT-combinations (CONTROL in
compatibility-style) of the keys. Note, that assignments made within a
session may get lost, since the profiles and the XXX\useXXX-macros
make (or clear) their own definitions when switching between several
files in the ring.

There may still be problems when using split screens or switching
between several buffers. Try paging to the top or end, when focus and
insertion position should become mismatched. (THE is still incomplete
in handling split screens properly in all situations).


MANIFEST OF FILES
-----------------
### Info files
COPYING             - GNU General Public License
README              - this file
README.*            - infos for other standalone parts of FW-macros
ChangeLog           - history of changes to the FW-macro package
fw_*.hlp            - help files for FW-macros
the_*.hlp           - help files for THE, extracted/token from the
                      original docs 
*.hlp               - other help files used in menus, for use???.the,...
KNOWNBUGS           - any questions?

### batches or shell scripts
fw.cmd              - batch to start THE with the FW-macros besides a
fw.bat                'normal' installation
fw.sh
rxtag.cmd           - batch for creating emacs-compatible TAGS file of
                      *.the, requires 'find' (unix-like!), 'etags', 'ls'
thes.cmd            - THE-server and THE-client (OS/2-only, automagically 
thec.cmd              called by fw-scripts, if feature 'CS' is in the
                      feature list)

### special files
*.mnu               - menu files

### profile stuff
fw.the              - main profile, should only be changed in rare cases
fwmkrc.the          - script to create a user specific profile
                      section, used by fw.the on initial call
fwsetrc.the         - macro for changing user settings
???\use???.the      - secondary profile to take up own key bindings and
                      other settings specific to files with ???-extension
                      this is, where you should make your adaptations
extension.the       - load file type specific settings and key bindings
define_???.the      - keybindings depending on the platform and
                      compatibility mode
color_???.the       - color definition used depending on the platform
                      and compatibility mode

### other macros
exitring.the        - macros used to manage the ring, also assigned to keys
locring.the
savering.the
qfiles.the
qring.the           

o.the               - opens file with same path and extension
pick.the            - reloads files present when THE is left with
                      'exitring' (C-K C-X), generated/updated during
                      this exit, not present initially

allx.the            - like 'all', but with regular expressions of 'grep'

fold.the            - example for folding, expanding and compressing
more.the              'the.man'
less.the

locale_???.the      - inserts locale characters at an US-keyboard
inserttext.the      - inserts text as a column of specified height, useful
                      to create tables, comments,..., easy to use with
                      1st S-F1 or A-INS and 2nd A-INS
fill.the            - formats paragraph according to margins set

qdir.the            - enter an arbitrary directory

qpoint.the          - shows points set in current file
qlocal.the          - shows settings local to current file
qthisline.the       - shows status of cursor position (key A-- in *.THE)
stackword.the       - brings text to cmdline
wcl.the             - counts words in each line

colorize.the        - visual setup of color sheme
pq.the              - processes queue from 'thec.cmd' (OS/2 only)

tex\*.*             - package to work with TeX
...\am*.the         - package from Agustin Martin Domingo for
                      inserting TeX-phrases (distributed separately)

other *.the         - mostly needed to make THE operate as you find it.
                      Mostly only intended to use bound to a key. Don't
                      care if you aren't interested in the details...

### other files
fw.Xresources       - X11-resources which can be included with 'xrdb'
fw_mask.tex         - mask with key bindings to lay around the function keys
the.ico             - my personal icon (OS/2)


CONTACT
-------
Author of this package:

Franz-Josef Wirtz,
Juelicher Str. 299,         email: fw@ecotopia.oche.de
D-52070 Aachen,
Germany

You can also contact Mark Hessling, but he's only maintaining the
sources of THE, not these macros.

Mark Hessling                   Email:       M.Hessling@qut.edu.au
PO Box 203                      Phone:              +617 3802 0800
Bellara                         http://www.lightlink.com/hessling/
QLD 4507                        **** Author of THE & Rexx/SQL ****
Australia                       ******* Maintainer PDCurses ******
                                ********** Member RexxLA *********

There are also mailing lists talking about THE, REXX and XEDIT and
clones in general. See the documentation for THE.


WHERE TO GET THE
----------------
THE is available from the following sites:

 North America:  ftp://uiarchive.cso.uiuc.edu/pub/packages/THE/
                 http://uiarchive.cso.uiuc.edu/
                 ftp://ftp.xylogics.com/pub/misc/THE/
 Germany:        ftp://ftp.germany.eu.net/pub/comp/sysv/THE/
                 ftp://ftp.rzg.mpg.de/pub/software/the/THE/
                 http://www.rzg.mpg.de/rzg/software/the/THE/
                 /afs/ipp-garching.mpg.de/common/soft/GNU/TAR/the/THE/
 Austria:        ftp://ftp.wu-wien.ac.at/pub/src/Editors/THE/
 Australia:      ftp://ftp.qut.edu.au/pub/markh/THE/
                 http://www.gu.edu.au/gext/the/markh.html

Files available:

thedos??.zip            - version ?.? DOS executable and documentation
thedjg??.zip            - version ?.? extended DOS executable and documentation
theos2??.zip            - version ?.? OS/2 executable and documentation
thew32??.zip            - version ?.? Win95/NT executable and documentation
thesrc??.zip            - source code for version ?.?
THE-?.?.tar.gz          - source code for version ?.?
thedoc??.zip            - HTML documentation for version ?.?

thedit21.zip            - version 2.1 MS-Windows 3.1 port (shareware)

The version placeholder ?? should be replaced by 25 or higher.

You will find FW-macros (and other macros) in a subdirectory named
'contrib'.


MANY THANKS TO
--------------
... you for trying this package

... Mark Hessling for his work done on THE and his help in
    developing this macro package.

... Agustin Martin Domingo for his extension of the TeX-mode and the
    discussions 

... Larry Margolis (margoli@watson.ibm.com) for his suggestion on
    creating a TAGS-file for THE-macros

... some guy on the net on giving the KISS-idea how to sort filenames
    by extensions

... Any contributors are welcome.


TIMESTAMP: May, 23rd 1998
---------

Now enjoy
Franz-Josef
