@database 003ae670-0
@master Ecstasy.guide
@$VER: 1.03
@author "Ali Graham"
@(c) "May-October 1995"
@remark Created with Heddley v1.1 (c) Edd Dumbill 1994

@node "Main" "Ecstasy "
@next "Legal Status"


    Ecstasy  --  @{i}A very configurable front-end for E programmers@{ui}.

             © May-October 1995                  by Ali Graham


    @{fg shine}This is v1.03. I accept no responsibility for any problems.
    You are advised to carefully read and note the disclaimer.@{fg text}


    @{"   Disclaimer    " link "Legal Status" 0}           You can't sue me!

    @{"  Distribution   " link "Distribution" 0}           Don't send any money! We'll bill you!
                                 Our operators are standing by...

    @{"  Introduction   " link "Intro" 0}           A short description of Ecstasy.

    @{"  Installation   " link "Installation" 0}           How to install Ecstasy.

    @{"  Requirements   " link "Requirements" 0}           What do you need to run Ecstasy?

    @{"     Usage       " link "Using Ecstasy" 0}           Instructions on use.

    @{"  Preferences    " link "Preferences" 0}           Configuring Ecstasy.

    @{"   EcstasyPrefs  " link "Menu Editor" 0}           Editing the menu.

    @{" Version History " link "Version History" 0}           What's happened so far.

    @{"  Still to come  " link "Still to Come" 0}           What's in the pipeline?

    @{"      Bugs       " link "Bugs" 0}           What don't work?
@endnode

@node "Legal Status" "Legal Status"
@next "Distribution"
@prev "Main"


So, it don't work.

Or you've received some damage from it.

Tough.

I hereby abjure (nice word :-) from any and all responsibilty concerning the
operation or lack thereof of this piece of software. I am gifting it with
electronic autonomy; it may wreak legal, physical and mental havoc without my
knowledge or responsibility.

However, having said that, it does work on MY system.
@endnode

@node "Distribution" "Distribution"
@next "Intro"
@prev "Legal Status"

 @{b}Distribution@{ub}

 I would prefer that no part of this distribution be modified in any way. I
 still possess full copyright over the enclosed software; I will not
 appreciate any transgressions upon this - either by claiming this as your
 own work, or by hacking it to produce work that is not mine. I'm sure it
 would be easy enough to do, but seeing hacked versions floating around just
 removes any pleasure I get from doing this.

 There's a phrase I always like to read in books, because I'm never QUITE
 sure what it means; "The author's moral rights have been asserted." Well,
 that applies here.

 Due to my parlous financial circumstances, I have been forced to release
 this program as '@{b}DebtWare@{ub}'. Yes, that's right, I am currently in debt to
 the tune of roughly AUS$600. If you can afford the registration fee of...
 hmm... $600..., then you have won a friend for life and willing servant.
 (only kidding :-)

 Seriously, I would like to think that anyone using this program regularly
 would send me whatever they can afford - the local equivalent of $5, $10
 or $15 in US currency. I find this program quite useful, but even I
 wouldn't want to pay any more than US$20...

 Rest assured that any contributions will elevate you to the top of the
 queue when it comes to fixing bugs, adding features etc.

 Donations in aid of reducing my debts can be directed to:

 Ali Graham
 15 Bakewell Rd
 Evandale  SA     <<--- that's South @{b}Australia@{ub}, not South Africa :-)
 Australia 5069


 @{b}Contacting the author@{ub}

 I would appreciate any bug reports, suggestions, etc which could guide
 future development of this program.

 I can be reached at these two E-Mail addresses:

 agraham@cleese.apana.org.au                 @{b}(preferred)@{ub}
 a0graham@teaching.cs.adelaide.edu.au
@endnode

@node "Intro" "Introduction"
@next "Installation"
@prev "Distribution"
 What is Ecstasy? Why should I @{"use" link "Using Ecstasy" 0} it?

Ecstasy is a front-end to the EC compiler (the main compiler for the E
language).

I guess you could use it for other languages as well... but certain elements
of it are biased towards E - things like the filter for the compiler output.

I was using a small program called EZ_E which I picked up from somewhere...
but I ended up getting annoyed with  it. It wasn't font sensitive, so it
looked a little funny on my screen. Even if you cancelled an operation, it
still continued anyway. (AAARGH!) It was extremely UNconfigurable.

So I created this...

What advantages does Ecstasy have?

*   Support for @{"WBStart-Handler" link "WBStart-Handler" 0}.

*   Font-sensitive GUI - I have struggled with GadTools to create a decent
    looking GUI, rather than opting for MUI/BGUI/Triton etc...

    Ecstasy will use any @{"font" link "Preferences" 0} you choose for its main interface.

*   Easily @{"configurable" link "Preferences" 0} interface.

*   Ecstasy has a menu reserved for configuration by the user. The @{"editor" link "Menu Editor" 0}
    for this is external to the rest of the program, to save memory.

*   Implemented as a @{"commodity" link "Tooltypes and the Command Line" 0}, for extra usability.

*   Will run on any @{"public screen" link "Using Ecstasy" 0}.

*   Has been tested/used for five months to develop @{"itself" link "About Ecstasy" 0}
    and other programs.

*   Ecstasy has none of the ugly input-output windows that plague programs
    of this type (although it used to ;-). Instead, the program will notify
    you of any unusual messages from the @{"compiler" link "Using Ecstasy" 0}.
@endnode

@node "Installation" "Installation"
@next "Requirements"
@prev "Intro"
 Installation is pretty simple - copy it to your E bin directory. (It will run
from anywhere else, as well, but this is a logical place to put it.)

Ecstasy needs certain libraries - all common, but someone out there may not
have ReqTools yet (like those lost tribes in Borneo :-). See @{"Requirements" link "Requirements" 0} for
details of these libraries.

If you wish to run files from their icons with Ecstasy, then you must have the
file @{"WBStart-Handler" link "WBStart-Handler" 0} in the L: directory. This file is provided with the
Ecstasy distribution. If this file is not found, then nothing untoward will
happen - files will merely be run from the command line instead of from
Workbench.

Also, once Ecstasy is running, you must configure it. See @{"Preferences" link "Preferences" 0} to find
out how to do this.
@endnode

@node "Requirements" "Requirements"
@next "Using Ecstasy"
@prev "Installation"
 Ecstasy @{b}REQUIRES@{ub} Workbench 2.0+. If you do not have a machine which is able
to run this program, then you are missing out on a lot more than just this
little utility! Almost all major programs these days will not run on WB 1.3
machines. Upgrade, and join the rest of us.

Also, Ecstasy uses the Reqtools library for its requesters.

Reqtools is © Nico Francois.

I have been using version 38.1248 - any problems that result MAY come from
using a version of Reqtools lower than this. I can't really say, but if there
are any problems then this could be something to try.


Specifically, Ecstasy needs these libraries in your LIBS: directory.

@{b}Asl.library@{ub}         (v37+) Provided as part of the OS. 

@{b}Commodities.library@{ub} (v37+) Provided as part of the OS.

@{b}Diskfont.library@{ub}    (v37+) Provided as part of the OS.

@{b}Icon.library@{ub}        (v37+) Provided as part of the OS.

@{b}Iffparse.library@{ub}    (v37+) Provided as part of the OS.

@{b}Reqtools.library@{ub}    (v38+) This is available in the public domain.


It will optionally use this handler:

@{b}WBStart-Handler@{ub}            Place this in the L: directory.
@endnode

@node "Using Ecstasy" "Using Ecstasy"
@next "Preferences"
@prev "Requirements"

 The actions Ecstasy will take depend on whether there is an 'active' file or
not. This is determined by whether you have selected a file to edit since you
started the program. The active file (if one exists) is shown - file name
only, without the path - in the box below the action buttons.

This active file can be changed using the small gadget with the question mark
on it next to the display window.

Key-short cuts exist for all the buttons - they are underlined on the buttons
themselves.
@endnode

@node "Preferences" "Menu Prefrences"
@next "Local Preferences"
@prev "Using Ecstasy"
These are the options you are asked to supply for the preferences option. It
is best to use absolute paths (i.e. from the root of the device you are
referring to) because the paths passed to the program by the preferences are
relative to the location of the program.

This options can be changed from the 'Project' menu.

@{b}Jump Screen:@{ub}        Use this option to jump to the next public screen.
                    However, if the public screen is in 'private' mode
                    (i.e., it is not allowing any visitor windows to
                    open) then Ecstasy will present a requester
                    complaining that it cannot open on that screen.

@{b}Work directory:@{ub}     This is the directory that contains all of your source
                    files. Ecstasy will CD to this directory when it starts
                    up. It will look for its various settings here in the
                    '.ecstasy' and '.ecstmenu' files.

@{b}Save to Icon:@{ub}       This saves the current working directory to the
                    program's icon. The next time the program is started, it
                    will CD to this directory and search for a config file
                    there.


These options can be changed from the 'Settings' menu.

@{b}Font:@{ub}               The font to use for the Ecstasy interface. You are
                    limited to using fonts between 6 and 18 points in size
                    (and even they make the window pretty big).

@{b}Editor:@{ub}             This should be a path to your preferred editor.


(Run editor         This is a setting which will only matter on start-up;
 on start)          it governs whether Ecstasy attempts to run the (saved)
                    editor with the (saved) active file.

(Wait for           This governs whether, if the named public screen that
 public screen)     Ecstasy should open on is not open, whether the program
                    should wait for it to open (after a certain configurable
                    time, it will put up a requester asking whether it
                    should continue waiting, open on the default public
                    screen or quit) or just open directly on the default
                    public screen.

@{b}Compiler:@{ub}           This is where you choose the location of your
                    compiler (usually EC in the /bin directory of the Amiga
                    E distribution, but you may want to run a different
                    version).

@{b}Compiler options:@{ub}   If you want to run your compiler with any command line
                    options, they can be entered here. For example, if
                    you wanted to debug a file using EDBG and compiling
                    with EC, you would open the compiler options requester
                    (RAmiga-C, or use the menu) and enter @{b}DEBUG@{ub}.

(Show unreferenced) Toggles reports of unreferenced variables in the
                    post-compilation requester.

(Show warnings)     Toggles reports of compiler warnings in the
                    post-compilation requester.

@{b}Debugger:@{ub}           This is where you choose the location of your
                    debugger (usually EDBG in the /bin directory of the Amiga
                    E distribution, but you may want to run a different
                    version).

@{b}Edit Actions Menu:@{ub}  This calls an external prefs program to edit the menu
                    (see @{"EcstasyPrefs" link "Menu Editor" 0}).

@{b}Save to Dir:@{ub}      This option saves the settings to the current directory.
@endnode

@node "Local Preferences" "Local Preferences"
@next "Menu Editor"
@prev "Preferences"
In writing this program, I wanted to easily support working on several
different programs at the same time. Therefore, while using Ecstasy it is
possible to save your settings to a small file (called '.ecstasy') in the
current directory of the program. This ensures that when you change
directories (and effectively change the project you are working on) you can
change the appearance of the GUI and the operation of Ecstasy's functions.

Each time you change Ecstasy's current directory, the program checks to see if
it can find a '.ecstasy' file in the new directory. If it cannot find it, then
the program settings remain as they were; if it can, then the settings are
changed.

The only option which is saved to the icon is the working directory. This
option has been separated from the others to emphasise this fact.

You can save your settings to the current directory using the 'Settings/Save
to Dir' menu option.
@endnode

@node "Menu Editor" "Menu Editor"
@next "Tooltypes and the Command Line"
@prev "Local Preferences"
This program serves as a menu editor for the (optional) 'Actions' menu.

I made this external to the rest of the program because it would have taken up
too much memory otherwise - another 25K or so for something not often used.
Instead it is called by Ecstasy, which expects to find it in the same
directory as itself.

In order to see what the program does, call it from within Ecstasy (use @{i}'Edit
Actions Menu'@{ui} or press @{i}Left-Amiga M@{ui}) and press @{b}Add@{ub}. You may then type a name
and an action to be associated with that name. There are two modes that this
action may be run in: @{b}CLI@{ub}, which executes it as if it had been typed in from
the command line, and @{b}WB@{ub}, which runs the named program using the
WBStart-Handler (and therefore expects to find an icon).

In order to place a line (menu bar) across the menu, just enter the word
'MENUBAR' (without quotes) in the 'Name' gadget. This line will be interpreted
by Ecstasy when it reads the saved menu prefs file ('.ecstmenu') back in.

You can therefore see that more complex actions can be easily set up by
executing scripts.... e.g. if I wanted to make three assigns and run two
programs with one menu selection, I would write a script to do these things,
place it in the S: directory, and then put 'Execute S:MyScript' in the Action
string gadget in the menu editor (using CLI mode, of course).

I decided to do this when I was on the point of adding hardwired support for
AutoBuild and FlushCache in the main program, and suddenly realized that it
would make much more sense to provide an expandable mechanism instead.

The program uses a standard GadTools listview interface... there are a few
things to mention though. When adding or editing an entry, make sure that you
have pressed 'Return' in the string gadget, otherwise the change will not
register. Also, I have limited this program to only allow 20 menu entries,
largely because this would unbalance the look of the menus.
@endnode

@node "Tooltypes and the Command Line" "Tooltypes and the Command Line"
@next "Version History"
@prev "Menu Editor"

 Ecstasy only has one application-specific tooltype:

    WORKDIR=<active directory>

 This points it to a default directory, where it expects to find
 file(s) that tell it how to @{"configure" link "Local Preferences" 0} itself for that particular
 project.

 Ecstasy also supports the normal system tooltypes which configure
 commodities:

    CX_POPUP=<either TRUE (or YES) or FALSE (or NO)>
    CX_POPKEY=<preferred hotkey combination>
    CX_PRIORITY=<priority in the commodities chain>

 Defaults for these are:

    CX_POPUP=TRUE
    CX_POPKEY=rawkey ctrl lalt e
    CX_PRIORITY=0

 These can also be invoked on the command line, as follows...

 'Ecstasy WORKDIR=hd1:Programming/MyProject/ CX_POPUP=YES' etc.
@endnode

@node "Version History" "Version History"
@next "Still to Come"
@prev "Tooltypes and the Command Line"


@{b}0.50a   (30.5.95)@{ub}

* Started version history :-)

* Added full selections for prefs, along with save/load for config.

* Dumped font load option until I can fix it so it stops crashing my machine
  :-)


@{b}0.55a   (31.5.95)@{ub}

* Added box showing the active file.


@{b}0.75a   (4.6.95)@{ub}

* Started AmigaGuide documentation.

* Font rendering now working perfectly - problem with differences between
  E 'normal' strings, E 'EStrings' and the strings Intuition expected :-)

* Truncated strings so they wouldn't over-run the text box (oops)

* Added 'Debug' and 'Shell' buttons.

* Added 'work directory' concept.... you can choose the current directory in
  the prefs.

* Fixed 'Debug' so it didn't lock up program (oops...)

* Changed routines to cope with operations being cancelled better.


@{b}0.80ß   (7.6.95)   LIMITED RELEASE VERSION.@{ub}

* Tidied up code... made font rendering screen sensitive.


@{b}0.85a   (13.6.95)@{ub}

* Prefs options shifted to menu - now they can be changed individually and
  only need to be saved when you want.

* Exit button removed - with close gadget and menu quit to choose from,
  another way out seemed like overkill.

* I/O window now always adaptive in height to size of main window.

* Bit the bullet and moved to reqtools.library - most serious users will have
  it permanently patched into memory anyway.

* Added compiler command line options, and saving/loading of them.

* Added config file identification. Now the program does not attempt to parse
  any and all files as configs...

* Ecstasy is now a commodity, with all CXExchange options enabled.

* Now extremely(!) font-sensitive.

* Added selector button for the active file box.

* Added key short-cuts for all gadgets.

* Added check before quit.


@{b}0.90a   (25.6.95)@{ub}

* Now saves/loads location of main window.

* If no executable, then compile and run: feature added.


@{b}0.93a   (29.6.95)@{ub}

* Fixed an exit bug - gadget list was being freed twice (oops!)

* Program now checks for OS version and prints out a response if the
  machine only has 1.3. Previously it just failed to run.

* Been wrestling with bugs in directory locking - all fixed now (touch wood).


@{b}0.97a   (3.7.95)@{ub}

* Added support for Stefan Becker's @{"WBStart-Handler" link "WBStart-Handler" 0}. Now, whenever you try
  to execute a file, the program checks to see if an icon exists. If it
  does, then the program is started with a simulated Workbench start.

* Bugfix: paths can now be provided in the tooltypes either with or without
  trailing slashes (e.g 'hd1:e/dev' OR 'hd1:e/dev/' are both acceptable).


@{b}0.98ß   (5.7.95)@{ub}  @{i}BETA VERSION@{ui}

* Ecstasy now correctly identifies the name of the executable it is running
  from. The name of the program is not hard-wired into it anymore.

* Changed default font (i.e. if preferred font could not be loaded) to
  the screen font instead of topaz/8. If the screen font cannot be loaded,
  THEN topaz/8 is used as an extra fallback.

* Bug: previously, if Ecstasy could not read any tooltypes to begin with,
  then it could not save any out either - fixed.

* Fixed an old bug where the view-window could leave garbage on redraws
  after a window re-render.


@{b}0.99ß (1.9.95)@{ub}

* Fixed small bug in window rendering to cope with (other peoples')
  machines :-)

* Made *ALL* file names active with full path - to avoid 'relativities'
  when locating program tools etc

* Fixed gadget handling - now checks for multiple button presses/commodities
  messages that may have occured while it was 'busy'. This would usually
  happen while compiling a large project, or compiling a project with an
  empty module-cache. Also ghosts the gadgets when the program cannot
  accept input while compiling.

* Removed i/o window - now notifies user of compiler errors via a requester.

* Added jump to public screen (is also saved in prefs). Program can
  optionally wait until this public screen opens.

* Added local prefs saved as a file in a project directory. Ecstasy can now
  change its operation 'on the fly' in reponse to the different demands of
  your programming.

* If the local settings file contains an active file, Ecstasy loads the
  editor with this file when it starts/changes directory. (optional)

* Made unreferenced check, warnings optional (via menu).

* Tidied up the icon save/dir save. Empty fields now saved as "NONE",
  scanned back in correctly.


@{b}1.00  (10.10.95)@{ub}

* Added 'Actions' menu, and the editor for it - see EcstasyPrefs.

* Made the editor external after realising that it increased the
  executable size by about 20K.

* Wiped out a few small buglets. Made compiler name and debugger
  name chooseable. Made program more useable with earlier versions
  of EC. Fixed Ecstasy's public screen handling - sometimes locks
  were left when they shouldn't have been. Fixed an old menu bug.


1.03  (13.10.95)

* Made an infinite-length strings module, and incorporated that internally.
  File requesters now have a 2K buffer space - should be safe. Fixed
  gadget rendering - I must have read the AutoDocs wrongly :-)
@endnode

@node "Still to Come" "Still to Come"
@next "Bugs"
@prev "Version History"

 Does anyone want these built in?? I could undertake to do
 any of these, but it depends on whether anyone wants them...

* An ARexx port.

* Support for using a default icon in env:sys/, rather
  than the one built into the program.

* Locale support - catalogs etc...

* MUI/Triton/BGUI versions...
@endnode

@node "Bugs" "Bugs"
@next "WBStart-Handler"
@prev "Still to Come"
 I have recently made some pretty wide-scale changes to this program,
 and some bugs popped up... I think I've gotten rid of them, though.

 I'm sure, however, that they teem unrestricted within the confines of my
 code, merely waiting until I release the program before raising their
 collective heads.

 If you think you have found one, first check (within the documentation)
 that it is not an 'implementation issue'... i.e. that it was not a
 deliberate choice due to the restrictions of operating system (or,
 indeed, those of the programmer ;-).

 One thing to note is that i have tried to make this program as font-
 sensitive as possible. However, I have only been able to test this
 on a couple of other machines, so I am not sure that it will work
 on all machines.

 If you find any bugs, then contact @{"me" link "Distribution" 0}.
@endnode

@node "WBStart-Handler" "WBStart-Handler"
@prev "Bugs"
 I used the most recent version of the WBStart-Handler development docs I
could find, for v1.3, on Fish Disk 896.

However, the version I use (and the version I have included with this program)
is v1.4. No problems have resulted in using this newer version.

If this file cannot be found, then the program will still run - however the
feature of starting programs from their icon will be lost.
@endnode

@node "About Ecstasy" "About Ecstasy"
 If anyone objects strongly to the name, then they can contact me. I'm sure it
will probably lead to me being arrested on some trumped-up drug charges, but
that's my problem.

I just wondered what the letter E means to most people :-)

(Does anyone remember the unlisted 11th song on the E.M.F. album
 'Schubert Dip', which was also titled "E.M.F."... and what that
 stood for??? ;-)
@endnode

@node "About Working" "Sweat and blood"
 Ouch! Well, I've only lost the source code due to memory/disk corruption once
so far.... painful!
@endnode