Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/030.lha/Dme.doc

Text File | 1986-11-10 | 21KB | 558 lines

DOC.TXT

DME V1.25 (c)CopyRight 1987, Matthew Dillon.  All Rights Reserved. This
software may be distributed for non profit only.  This software is
shareware, but I won't get on anybody's case or whine if I don't make any
money from it.

    Matthew Dillon        contribute if you wish.
    891 Regal Rd
    Berkeley, Ca. 94708

    USENET   ihnp4!ucbvax!dillon
    ARPANET  [e-mail]

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

I   Overview
II  Keymapping        keymapping
III Command Sequences    DME commands
IV  File Particulars    notes on loading and saving files
V   Revision Summary    revision numbering
VI  Compiling        compiling instructions

                    I
                 OVERVIEW

See REVISIONS section for revisions.  DME is a WYSIWYG editor designed
mainly for programmers.  Although it is not a word processor, it does
include some word processing features such as Word-Wrap and automatic
paragraph formatting.  Here is a quick 'features' list:

    -control language based on a rich command set accessed manually
     or via arbitrary mapping of keys.  (Every key may be mapped to 16
     different things)

    -fast visual response (it scrolls quickly)

    -title-line statistics showing your current position in the file,
     file name, whether the file has been modified or not, etc...

    -Multiple Windows, ability to iconify windows

    -Word Wrap and automatic paragraph formatting.

DME has been designed to allow easy expansion, and I intend to make many
future improvments.  It has not been designed for user friendliness, but is
straight forward if you read this document fully.

DME can take any number of arguments.  Any argument without a '-' in front
of it is considered to be a file.   Normally, DME will automatically SOURCE
two script file, S:.EDRC, and the .EDRC in your current directory. These
files do not have to exist. These script files usually contain mappings and
do things like turn on word wrap and set the right margin.

    FLAGS:
        -ffilename        -source this script file instead of .EDRC
        -b            -normally when multiple files are specified,
                 DME opens them with small windows.  This opens
                 them with normal sized windows.

        -tN     -Open the window on scan line N
        -lN     -Open the window offset N scan columns
        -wN     -Make the window N pixels wide
        -hN     -Make the window N pixels high



                    II
                 KEYMAPPING

MOUSE SELECT (LEFT ) BUTTON:
    There is no designation to map the left button.

    positions cursor at the indicated spot.  The cursor now tracks the
    mouse.


MOUSE MENU (RIGHT) BUTTON:
    There is no designation to map the right button.

    This button iconifies the current active window if not iconified, and
    de-iconifies the window if iconified (Try IT!).  The iconification
    features:
    -Remembers original window size and placement
    -Remembers placement of iconified window when you re-iconify later.

    Currently, you will crash the machine if you run out of memory and DME
    is unable to open the icon window or original window, so be careful.


KEYBOARD:

The rest of the Functional interface for DME is based on keymappings and a
rich command set.  Unlike other text editors, any non-qualifier key in DME
may have any meaning whatsoever.  It just so happens that the default
keymappings assign such things as the `return' key to the RETURN function,
the `up' key to the UP function, etc...  Keys are named by their keycap
labels with the following exceptions:

    the name for Back-Space is    BS
    the name for numeric keypad keys are prepended with an NK, except for
    the Enter key which is named 'ENTER'.
    The four cursor control keys are labeled UP, DOWN, LEFT, and RIGHT

*NOTE*    You must type commands in lower-case, except for text, which can be
either lower or upper case, and for upper-case alpha keys when specifying
keymaps (i.e.  A and s-a are the same key).  The exception is the AMIGA
qualifier key, which uses 'A' instead of 'a'(Alt).

Each key may be qualified with any combination of CTRL, ALT, SHIFT, or
AMIGA Keys.  With four qualifier keys, you can assign up to 16 different
meanings per physical (except qualifier keys) key on the keyboard.

NOTE: The CAPS-LOCK, when lit, is equivalent to SHIFT only for Alpha keys.

NOTE: The AMIGA-ALT (aA) combination isn't very usable since Intuition uses
the sequence to duplicate a Mouse SELECT.  Other AMIGA sequences are used
by intuition for mouse movement and other things.

    ***EXAMPLES:***

    tab tab
    a-a ALT a
    A-a AMIGA a
    sA-a    SHIFT AMIGA a
    s-tab    SHIFT tab
    c-tab    CTRL tab
    ac-?    ALT-CTRL ?
    s-f5    SHIFT F5
    nk0 Numeric Keypad 0
    cs-nk0    CTRL SHIFT Numeric Keypad 0

    ***************

The Default Mappings are as follows:

    All Printable Ascii keys mapped to their ascii equivalent
    BS, DEL, UP, DOWN, LEFT, RIGHT, TAB, S-TAB, ENTER mapped properly

    `s- '       Shift Space is Mapped to space
    backspace    Back Space
    tab Tab
    s-tab    Back tab
    enter    the RETURN command
    return    `return insline up firstnb down'
    esc Escape into command mode
    del Delete character
    s-del    Delete line
    c-del    Remove to end of line
    up        cursor up
    down    cursor down
    left    cursor left
    right    cursor right
    s-up    top of text
    s-down    bottom of text
    s-left    first column
    s-right    last column (one past the last non-blank on a line)
    c-up    page up
    c-down    page down
    c-q Quit
    c-w TOGGLE WORD WRAP MODE
    f1        Prompts for file to insert
    f2        Prompts for new file to replace current text with
    f3        Prompts for new file to place into new window
    f7        Prompts for filename to save marked block to
    f8        Saves current text and then does an 'f2'
    f9        Saves current text, but does not quit
    f10 Saves current text and quits.
    c-r Word Right
    c-l Word Left
    c-i insert mode on
    c-o insert mode off
    c-/ Prompts for search pattern
    c-p search previous occurance
    c-n search next occurance
    c-s `split first down' ... fancy split line
    c-u Unblock a block
    c-b Mark start/end of a block
    a-s SOURCE a block of text as if it were a script file
    sa-s    SOURCE the current line of text as if it were a script file
    a-d delete block
    a-c copy block
    a-m move block
    c-f reformat paragraph
    c-g Prompts for line to GOTO to.
    c-j join next line to this line.


                    III
                 COMMAND SEQUENCES

DME has a rich command set which allows you to embed commands within
commands, or specify multiple commands in a row.  A command consists of a
KEYWORD followed by a FIXED number of arguments (0, 1, 2...).  The argument
delimeter in DME is a SPACE.  Therefore, to embed strings containing spaces
as a single argument, you must surround the string with `string'
(backquote-string-quote).  TEXT to be written as if typed is also specified
via a string in backquote-quotes.  For example:

    right right `hello' right right `hello' enter down
    map f4 `right right' map f5 `left left'
    map f4 ``hello''

Reiterating (because this is important!)... If a command expects ONE
argument, then it really does expect a single argument, and any remaining
arguments are thought to be the next command... so:

    map f4 right
                    -right is only one word, so no need
                     for `'.
    map f4 `right right'
                    -we want to map f4 to two rights... we
                     need the `' or the second right will
                     not be part of the map.

    map c-del `repeat cright del'
                    -this is already implimented as REMEOL,
                     but shown here for clarity.

Some arguments will eventually be fed through the command interpreter more
than once.  The MAP command is a good example.    When you execute a MAP
command, the first run through the command interpreter installs the map
string minus a set of quotes.  So, if you want to specify text, you must
enclose the text in two sets of ``text'' because the map string gets passed
through the command interpreter again when you hit the mapped key.  Here
are some more complex examples:

    map f4 `right right `hello' left left'      *RIGHT*
    map f4 right right hello left left        *WRONG*

    map f4 `map f4 ``hello'''
                    -the first time you hit F4, it's command
                     is to re-map itself to the TEXT `hello'.
                     (gads!).

    map c-i `repeat tr `` '''
                    -example of how to embed a space in a
                     map and repeat (goes through command
                     interpreter three times!).


An easy way to fool around executing commands or making maps is either to
use the ESC key (which enters command mode), or  a-S (alt-shift-s), which
EXECUTES the current DME line that the cursor is on.... so you can use DME
to edit and test your new keymappings.


!!!!!!!!!! NOTE NOTE NOTE NOTE NOTE !!!!!!!!!!!!!! You must type commands
in LOWER case. They are in upper case here for visibility.

    COMMAND LIST



    `text'          -enter text as if typed.
    key     -execute a keymap as a macro (example:  c-a)
    IF cnd act        -IF/WHILE/IFELSE.. SEE BELOW
    WHILE cnd act
    IFELSE cnd ifact elseact

    ESC     -toggle manual command entry mode
    ESCIMM arg        -go into command entry mode prompting with a predefined
             string.
    LAST        -move one beyond the last non-space in a line.
    FIRST        -move to column 1
    DOWNADD        -cursor down.  If at bottom of text, add a line.
    MAP key map     -map a key to a keymap
    UNMAP key        -unmap a key
    UP            -cursor up
    DOWN        -cursor down
    LEFT        -cursor left
    RIGHT        -cursor right
    PAGEUP        -pageup a partial page (see PAGESET)
    PAGEDOWN        -pagedown a partial page (see PAGESET)
    PAGESET n        -n PERCENT (0 to 100). page step size relative to the
             current number of rows in the window.
    RETURN        -same as `FIRST DOWNADD'
    WLEFT        -move to beginning of previous word.  If in the middle
             of a word, move to beginning of current word.

    WRIGHT        -move to beginning of next word
    BS            -backspace, moving text to the right of the cursor
             leftward.
    BACK        -same as BS
    DEL     -delete char under cursor (cursor does not move),
             moving text to the right leftward.
    INSLINE        -insert line
    DELINE        -delete line
    TAB     -forward tab
    BACKTAB        -backward tab
    TABSTOP N        -Set tab stops every N
    NEWFILE name    -replace current text with new file
    INSFILE name    -insert a file into the current text.
    TLATE [+/-]N    -translate character by +N or -N, or set character to
             exactly N if no + or -. (e.g. TLATE +65 TLATE 3)
    SAVEOLD        -save current text under current name
    SAVEAS file     -save current text under a different name
    TOP     -Move to Top of File
    BOTTOM        -Move to Bottom of File
    SOURCE file     -source a script file
    BSOURCE        -source current text block as if it were a script file
    FIRSTNB        -Move to first non-blank in line.
    REMEOL        -Remove text under and beyond the cursor.
    QUIT        -quit
    FINDSTR string  -SET the search string pattern
    REPSTR string   -SET the replace string pattern
    FIND string     -SET the search pattern and do a NEXT
    NEXT        -find next occurance of search pattern
    PREV        -find previous occurance of search pattern
    FINDR s1 s2     -Set find and replace patterns and do one find/rep.
    NEXTR        -find next occurance and replace
    PREVR        -find previous occurance and replace
    SPLIT        -Split line at cursor
    JOIN        -join next line to line at cursor
    REPEAT cnt comm -SEE BELOW
    INSERTMODE what -set INSERTMODE.  what = on, off, or toggle
    SCREENTOP        -Move cursor to the top of the screen
    SCREENBOTTOM    -Move cursor to the bottom of the screen.
    GOTO BLOCK        -Goto the beginning of the marked block
    GOTO [+/-]N     -Goto an absolute or relative line number
    BLOCK        -Set start or end of block
    UNBLOCK        -clear the block markers.
    BCOPY        -copy block before cursor line
    BMOVE        -move block before cursor line
    BDELETE        -delete the block
    BSAVE file        -save the block to a file
    SAVEMAP file    -save user keymappings
    SAVESMAP file   -save all keymappings, including system keymaps
    TOGGLE N        -flip toggle array entry N    (See IF)
    SETTOGGLE N     -set toggle array entry N
    RESETTOGGLE N   -clear toggle array entry N
    NEWWINDOW        -open newwindow
    SAVETABS on/off -Optimize file saves by crunching spaces to tabs.  The
             default is OFF.
    LEFTEDGE N        -set leftedge in pixels for any new window
    TOPEDGE N        -set topedge in pixels for any new window
    WIDTH N        -set width in pixels for any new window
    HEIGHT N        -set height in pixels for any new window
    RESIZE cols rows-Resize current window. E.G:  `resize 70 23'
    MARGIN N        -set WordWrap and paragraph formatting margin
    WORDWRAP on/off/toggle  -Word Wrap mode
    REFORMAT        -reformat paragraph using the margin.


    -------------------------------------------------------------------
    Command which cause a command line to abort (e.g. in repeat, while):

    FIND[R]/NEXT[R]/PREV[R]  when the string is not found.  NEXT stops at
    the end of the file, PREV stops at the beginning.

    DOWN,LEFT,RIGHT,UP    when the operation cannot be done.
    -------------------------------------------------------------------


    REPEAT N arg    -Repeat `arg' N times.  Apart from being a number, N
             can also be one of:

            line    Current line # (lines begin at 1)
            lbot    #lines to the bottom, including current line
            cleft    column # (cols begin at 0)
            cright    #chars to eol, including current char under cursor
            tr    #char positions to next tab
            tl    #char positions to next back tab

            Certain commands can abort a REPEAT loop.  Specifically,
            any FIND[R], NEXT[R], or PREV[R] in which the search
            string is NOT found will abort a REPEAT.

            Specifying -1 as N causes REPEAT to go on forever
            (well, actually, 0xFFFFFFFF times) or until an abort.

    IF [!]condition arg
    WHILE [!]condition arg
    IFELSE [!]condition arg elsearg

        If the specified condition is true, execute the argument.  For
        WHILE, the argument is executed until the condition is false
        (be careful!).

        the optional '!' inverts the logic.

        Conditions:

        #        if toggle entry # is SET
        t        if On line 1
        b        if On last line
        l        if At column 0
        r        if At end of line (spaces below and beyond)
        m        if Text has been modified
        i        if in insert mode
        x[<=>]# if column position (starts at 1) is (any OR combo of
            <, =, or >) than some number.  Example:   x<20
        y[<=>]# if Line number (starts at 1) is (same as for x)
        cl        character under cursor is lower case alpha
        cu        character under cursor is upper case alpha
        ca        character under cursor is alpha-numeric
        cn        character under cursor is numeric
        c[<=>]# character under cursor is ascii code # (# in decimal)
            optional conditionals as in 'x' and 'y'.
        cb        cursor within a block

    Example: simulating an insert mode toggle: ALT-i (not CTL-i)

     map a-i `ifelse 0 `toggle 0 insertmode OFF' `toggle 0 insertmode ON''

    Example: while lower case, map to upper case and move right.

     map c-U `while cl `tlate -32 right''

     if c<32 ``char under cursor is smaller than 32''
     if c<>32 ``char under cursor is not equal to 32''
     while !b down


    WARNING:    It is possible to get into infinite loops with REPEAT and
        WHILE.    Currently, BREAK is *not* handled by the open
        window, but by whatever executed DME.  That is, you must
        either Ctl-C from your CLI, or send a BREAK to the DME
        process.  I hope to fix this soon.


                    IV
                 FILE PARTICULARS

No Matter what you set internal tabs to, tabs in disk files will be 8. DME
by default doesn't bother to optimize when writing out files and simply
uses spaces.  If you `SAVETABS on' before saving (or in your S:.EDRC,
etc...), DME will attempt to optimize the file by placing TABS in
appropriate places.  DME will not place any TABS after the first single,
back, or double quote is encountered in a line.  If this does not cover
every situation in your particular application that you want to be *sure*
no tabs will occur in sensitive sections, then you should not use `SAVETABS
on'.

The command to save the current document under the default name is SAVEOLD,
*not* SAVE.  SAVE is not a valid command.  This is to prevent people who
have not read the documentation from assuming 'save' takes an argument (and
screwing up their work).  SAVEOLD does NOT take an argument, SAVEAS does.


                    V
                  REVISION SUMMARY

Problems Still not resolved:

    -cannot block move/copy accross windows (must BSAVE to, say, the pipe:
     device)
    -still problems if you resize the window while DME is doing
     continuous screen operations (think it's the graphics library).
    -cannot type CTRL-C to break out of infinite loop... must use
     workbench C:BREAK command.
    -Blocks are not highlighted.
    -no 'dumb user' prompts.
    -no 'change working directory'... though this really isn't a bug.
     putting it in means that I would have to backtrace every filename
     so DME wouldn't get confused.  As it is, I think typing in paths
     isn't much of a big deal for people, so.... poof.


V1.25 RELEASE

    -BSAVE does NOT UNBLOCK after saving (switch in functionality yet again)
    -various bugs fixed (IF, tabs on file save)
    -New Commands: MARGIN, REFORMAT, WORDWRAP, RESIZE,
           TOPEDGE, LEFTEDGE, WIDTH, HEIGHT
    -Command line options added for setting the window size and an optional
     specified script file (when specified, local .EDRC not sourced).

    -Enhanced Commands: IF  ..more control with conditions, addition of
                  a couple more specifications.
               JOIN .. functionality slightly changed
    -keymaps may now be used as macros in other commands. (macros)
    -New keymaps added to the default set.
    -Mouse movement cleaned up a little.

V1.24 Internal

V1.23 RELEASE
    -S:.EDRC now sourced instead of C:.EDRC
    -User keymappings now work in COMMAND mode (when you hit ESC).
    -You can now map the Amiga keys ('A' for Amiga, since 'a' is alt).
    -Enhanced Commands: IF/IFELSE/WHILE (optional '!' in front of cond)
            new condition 'cb' 'character in selected block'
            GOTO (can now say `goto block')
    -NewCommands:    PAGESET SAVETABS
    -Writing TABS (always 8) out to disk to save space now supported.

V1.22 RELEASE (BUF FIXES FROM 1.20)
    -'newfile' fixed
V1.21 RELEASE (BUG FIXES FROM 1.20)
    -iconify and window handling fixed
    -left mouse button now tracks the mouse.
V1.20 RELEASE
    -bug fixes: bsave now unmarks the block, bdelete now sets 'modified' flag.
        (other small fixes).
    -enhancements: overwrite mode status indicator, find, find-replace now
        completely implemented (yahhoo!!!)
    -changed commands:    FIND NEXT PREV: no longer loop back to the top of
        file or top->bottom in the case of PREV.  DELINE will now delete
        text on the line if there is only one line of text.
    -enhanced commands: GOTO REPEAT
    -new commands: SAVEMAP SAVESMAP TOGGLE SETTOGGLE RESETTOGGLE TLATE
           IF IFELSE WHILE BSOURCE
           FINDSTR REPSTR FINDR NEXTR PREVR
           NEWWINDOW
    -new keymappings: (see a-s, a-S, f3)
    -window iconification with mouse menu button.


V1.12 RELEASE
    -cursor is now pen #3 rather than #1.
    -changeover to AZTEC C, smaller executable.
    -now maps shift space to a space.
    -new commands: REMEOL, WLEFT, WRIGHT
    -display bug fixes (SPLIT)
    -FIND/PREV/NEXT will now abort a REPEAT if string not found.

V1.11 RELEASE NOTES
    -Bug fixes (mainly graphical mistakes).
    -User keymappings are disabled in command mode (so you can unmap
      single ascii characters you may have mapped).
    -Illegal key combinations no longer give garbage (e.g. ALT-CURSOR-DOWN)
      you can, of course, still map them to anything you wish.
    -Save now checks for error conditions on write.
    -Uses Default Console Keymap (i.e. no longer assumes USA)... but there
      *is* some stangeness.

V1.00 RELEASE NOTES
    -has find, but no replace function
    -marked blocks are not highlighted
    -assumes USA keyboard            (fixed 1.11)
    -disk files written out use spaces instead of tabs&spaces
    -No scroll bar yet.


                    VI
                COMPILING


DME now compiles under AZTEC.  You must compile with the 32 bit int option,
but may use the small code/data model.    You must use V3.00 or above of
MY.LIB    (MY32.LIB), dated MARCH 1987

    cc +L -S NAME.c        (for each .C module)
    ln *.o -lmy32 -lc32 +Q


To compile DME under lattice requires the MY.LIB version 3.00 or above:

    lc1 -oram: -iinclude: NAME.C
    lc2 -s -v -oNAME.o ram:NAME.q

    blink lattice:Astartup.obj library lib:my.lib+lib:amiga.lib to ram:dme ND