Documentation for: rem-ext42.r

REM v0.4.2
~~~~~~~~~~~

  (c) 2000,2001 Cal Dixon
  Please report all bugs to: rebol@programmer.net

Introduction and quickstart information:

--
May 1, 2001 release: Sorry, still no rewrite or expansion on the manual, but there were some
corrections and some bugfixes in the program to bring REM in line with Rebol/Core 2.5 and the
release of Rebol/View 1.1
There is now limited support in REM for remote file editing, although it still needs work.
--

  This document is unfinished and badly written, sorry, maybe the next one will be better.
REM is a fairly normal text editor in most respects, most things should be as you expect in a
text editor.  REM runs in the standard Rebol console, so the mouse and function keys are not
available.  Most commands are performed by either pressing 'control' and a letter at the same
time, or by pressing 'ESCape' followed by a letter.  At many of the prompts you can use the
up and down arrows to select from a list of options.

   Default keymap reference:

      Ctrl-Y        Paste text
      Ctrl-K        Cut line
      Ctrl-T        Cut region
      Ctrl-G        Copy region
      Ctrl-D        Set mark
      Ctrl-F        Swap cursor and mark
      Ctrl-J        Newline with auto-indent
      Ctrl-S        Search for text
      Ctrl-R        Search and Replace
      Ctrl-E        Lookup word under cursor with Rebol 'HELP function
      Ctrl-L        Redraw the screen
      HOME          Move to start of line
      END           Move to end of line
      ESC+Right     Move right one word
      ESC+Left      Move left one word
      ESC+Up        Move to start of file
      ESC+Down      Move to end of file
      ESC+h         Show help
      ESC+l         Load file (replaces current file)
      ESC+o         Open file
      ESC+n         Open new (blank) file
      ESC+s         Save file
      ESC+a         Save As file (choose a new filename)
      ESC+x         Close current file
      ESC+b         Switch to any open file
      ESC+d         Attempt to run current file as a Rebol script (and capture any output)
      ESC+m         Menu (use the up and down arrow keys to choose an option
      Ctrl-Q        Quit without saving
      ESC+q         Quit (asks to save any modified open files)

   Usage from rebol prompt:

       EDIT /file filename /string text /function the-function /config cfg /resume

       /file opens the specified file and returns the current filename when editing is complete
       /string allows editing of the string and returns the changed version
       /function opens the source of the function, and returns a function built from the
          edited version or a do-nothing function if the new version can't be loaded
       /config allows the spefication of an additional configuration file
       /resume will restore the editor to the state it was left in after the last call to 'edit

   Usage from system command line:

      /path/to/rebol -s rem4.r filename

      Obviously this will vary slightly between platforms.  If no filename argument is supplied
      on the command line then you will just get a standard Rebol prompt with the 'edit
      function available in the global context.

Overview:

   Now for the more complicated stuff ;-)

   First, about the name: REM is stands for "Rebol Editor Macros", it was named after EMacs,
which it was intended to resemble (somewhat).  It is also a stupid joke (rem was the comment
command in basic and in DOS batch files - it was short for "REMark").

   At first glance the name may seem odd; there is no obvious support for macros in this program.
The macro capability is there however, it just requires using a configuration file.  Any key or
series of keypresses can be mapped to whatever function you want, and the entire Rebol language
is available as a macro language.  More on this in the next section...

   Due to the difficulty of providing complex file requestors and pop-up menus in a text-only
console, I decided to use Rebol's command line history feature to provide those functions.  The
most obvious use of the is the menu (ESC+m) command.  However, the various load and save
functions also make use of this.  They appear to be simple filename input fields, but you can
scroll through all files in the current directory just by pressing 'UP'.  If you enter the name
of a directory (including ".." for parent directory) REM will change the current directory.  If
you enter a filename ending with the "/" character, and no directory of that name exists, REM
will ask if you want to create it.  It's not quite as nice as a real file-requestor, but it's
pretty useful.  If you are running under Rebol/View REM will use the standard view requestors
for files and confirmations.

   Currently the shortcut-keys for undo and redo are ESC+z and ESC+Z.  Once I've done a bit more testing, and gotten some feedback on what keys to map them to, I'll remap them and list them in
the help.  REM has unlimited levels of undo and redo.

   Another easy to miss feature is that if you run REM under Rebol/View, the cut, copy and
paste functions are integrated with the system clipboard. 

   Finally, check out the "command" (ESC+ESC) and "rebol help" (Ctrl-E) features.  Help looks
up the word under the cursor using the standard Rebol 'HELP function and displays the results
as a new file (just press ESC+x to close it).  Command displays a prompt where you can enter one
line of Rebol code (including REM's internal commands).  The result will be displayed at the
bottom of the screen (on the line where the prompt appeared), and if any console output is
produced it will be loaded as a new file (just like with the help feature above).

Configuration files:

   By default REM will load a configuration file called "rem.cfg", looking first in the current
directory, then in the REBOL_HOME directory.  You can specify an addition configuration file
with the /config refinement to the 'edit function.

   REM configuration files can contain normal rebol code plus calls to the following functions:

   map key [string!] action [block!]
      maps a specified series of keys to an action. the action can contain calls to internal
      REM editor functions (these are not currently documented).  If the key (or keys) is
      already mapped to something the newest mapping takes precedence 
   menu-item menu-name [string!] menu-label [string!] shortcut [string!] action [block!]
      If no menu with the given name exists, creates it, otherwise adds the specified option
      to the menu.  Much more should be said here, for now - look at the source for examples
   include filename [file! url!]
      processes an additional configuration file.  it will be searched for in the same manner
      as the default config file.
   startup action [block!]
      Just executes a block of code in the macro context
      if you need to use the internal editor function you must do so within a startup block.
   set-help text [string!]
      Replaces the internal REM help with the specified text
   default-title-bar
      This is not a function to call, but can be redefined (as you would normally in Rebol),
      to change the title bar at the bottom of the display.  I don't recommend doing this,
      but th possiblity is there.
   locate-file filename [file!]
      checks the current directory and the REBOL_HOME directory for a file, I'm not going to
      bother explaining this one now, but it's there if you need it.

   Eventually this section will contain explanations of all the internal functions that are
available in your macros, for now, look at the default config in the REM source, and the
'editor and 'tools objects in the source - where the functions are defined.

Advanced usage from the rebol prompt:

   I'm getting tired (it's 3am right now), so this section may have to wait until the next
release, for now I'd just like to note that although any of the refinements to 'edit can be
used in combination, there is only one return value - therefore there is a precedance in
determining which value will be returns, in order from lowest to highest it is:
   /resume
   /file
   /function
   /string

   Also, the /file refinement will allow the use of a url! instead of a file.  This was broken
in previous releases, but should work now.  The REM console-mode file requestor also accepts
url!s for filenames, however, the standard /View file request can't handle url!s yet.  Until
I find a better workaround for this, entering anything containing "://" in the /View file
requestor will bring up the console-mode file prompt.

Embedding REM in other scripts:

   Umm, maybe next time... For now - it can be done, and was the original reason for the /string
refinement.

Internals:

   Yeah right.  I'll write this section eventually, until then, read the source, it's not TOO
complicated...