Acorn User 1/AU_CD1.iso/demos/a_to_i/dbedit/!DBEdit/DBEditHelp

Text File | 1992-09-06 | 17KB | 451 lines

---------------- BDEdit Online help facility -----------------

Help is available on many topics for this editor. To allow
easy navigation around this help file, you may build an index
using the search string <--


-- Active Index

Type in one or two search strings (such as DEF) to build an
active index of all lines containing either or both of the
search strings.

Clicking on any line within the index causes the equivalent
line in the associated file to be scrolled on screen.

Due to speed constraints (the indexes must be rebuilt every
time the primary program is renumbered), for BASIC files the
search string is tokenised to allow direct matching against
the source. For this reason, if you are indexing strings
that include reserved words you must type the whole word or
a valid shortform using the standard "dot" format (Eg P. for
PRINT).

All of the search options shown in the "Options" box off
the "Search" menu may be used to enhance the capabilities of
the function.


-- Copy Sequence

The copy sequence available from the Archimedes command line
and ArmBE is also available in this editor.

Press Copy or Ctrl Copy (depending on the setting within the
profile) to invoke the function and the caret will split into
two, with the copy caret in a different colour to show the
new mode.
The Copy key now copies the character from the right of the
copy caret to the right of the line caret. The arrow keys move
the copy caret, and it may also be set into a new window via
clicking with the mouse or using Ctrl F2. The Delete key
deletes the character to the left of the line caret. Copy
sequence mode is ended if the Escape or Enter key is pressed.

While in Copy mode, Shift copy copies the current word (or
string if the caret is immediately to the left of a double
quote), and Ctrl Copy copies all text to the end of the line.


-- CSD

The currently selected directory (CSD) may be set in two ways.
The first is to open the menu on a window containing a file
from the required directory and choose the "Set CSD" option
off the "Misc" submenu.
The other is to drag any directory or application-directory
icon onto the DBEdit icon on the bar or to any open DBEdit
window.


-- Error throwbacks

DBEdit supports a facility whereby errors in any running
BASIC program can be captured and displayed. The errors can
occur in multi-tasking or single-tasking programs.

To invoke this facility all that has to be done is to have a
copy of the program loaded into the editor. It can then be
run with Ctrl R or with a double click on its filer entry.

Any errors that occur in the program will be displayed by the
Wimp as normal, then an Error index will be shown with the
new error.
This index works like normal indexes in that clicking on the
line displays the applicable program line.


-- Find and Replace

There is space for four Find strings which allows multiple
search strings to be retained and reused.
The fourth text will only be found within the current
selection if there is one, and doubles as the search string
to be replaced by the Replace function.
While the caret is on an edit window, all the combinations of
shifted and ctrl'ed F7 and F8 may be used.

All of the search options shown in the "Options" box off
the "Search" menu may be used to enhance the capabilites of
the function.

Use Ctrl B to return to where the Find was initiated.


-- Incremental search

Incremental search is a simple way of driving the first line
of the Find box, with one major enhancement. Instead of typing
in a whole word then clicking go, simply press F8 (to search
forwards) or F7 (to search back) then start typing the search
string.
DBEdit will immediately start looking for the required string
based on what has been typed so far. As soon as the screen
shows the line wanted, just press escape to return to editing
mode.
As with Copy mode, the caret changes colour to indicate the
current mode of operation.

If you accidently type a wrong character, press delete to
remove it from the string typed so far.

The Find box echos the characters as you type.

Use Ctrl B to return to where the incremental search was
initiated.


-- Indenting

Automatic indenting may be turned on via the Profile box of
the icon bar menu. This lines up new lines and split lines
under the previously typed line.

To indent a BASIC selection or program LISTO 7 style, choose
the menu option "Indent" off the "Modify" menu, or press
Ctrl N. If there is a selection, then the lines of the
selection will be reindented based on the first non blank,
non REMed line of the selection.
If there is no selection on this file, the whole program will
be reindented.

To suit different programmer indentation styles you may
set zero to nine spaces per indent via the "Profile" box.
This indent distance is also used when TAB or Shift TAB is
pressed if the profile is set appropriately.


-- Keyboard Commands

Arrow keys

  ⇦ ⇨ ⇩ ⇧ : Move the caret one character position.
Shift ⇦ ⇨ : Move the caret three positions sideways.
Shift ⇩ ⇧ : Move the caret and scroll the window one page.
Ctrl  ⇦ ⇨ : Move the caret to the end of the line.
Ctrl  ⇩ ⇧ : Move the caret to the end of the file.

Control keys

Ctrl 1 : Find First using One Key search string 1
Ctrl 2 : Find First using One Key search string 2
Ctrl 3 : Find First using One Key search string 3
Ctrl 4 : Find First using One Key search string 4
Ctrl A : Set the selection to include the caret line.
Ctrl B : Go back to where the last find was initiated
Ctrl C : Copy the selection directly after the caret line.
Ctrl F : Display the Find box.
Ctrl G : Display the statistics box; into which a line
         number can be typed to position the caret.
Ctrl I : Toggle insert mode on and off.
Ctrl J : Join the current line to the next separated by a
         colon.
Ctrl K : Toggle the setting of the "Keep Select" flag.
Ctrl L : Locate a marker previously set by the Ctrl P command.
Ctrl N : Indent the file or current selection.
Ctrl O : Open the Undo box.
Ctrl P : Mark the current position for the Ctrl L locate
         command.
Ctrl Q : Refresh the open indexes.
Ctrl R : Save the program to WimpScrap and run it from there.
Ctrl S : Swap the case of the character following the caret.
Ctrl T : Toggle the input focus window between the back and
         front of the desktop.
Ctrl U : Clear the current line of text.
Ctrl V : Move the current selection following the caret line.
Ctrl W : Split the current view. If the caret is currently on
         a line containing a PROCedure or FuNction call, the
         new view will be positioned to the appropriate DEF
         line.
Ctrl X : Delete the current selection.
Ctrl Z : Clear the current selection.

Function Keys

      F1 : Display this help document.
Shift F1 : Join the current line to the next separated by a
           colon.
Ctrl  F1 : Split the current line at the caret. The split off
           text will be indented to the same level as the
           current line if Auto Indent is on.
Ctrl  F2 : Step the caret onto the next open view of this file.
      F3 : Pop up the "Save As:" box to save the whole file.
      F4 : Pop up the Find box.
Ctrl  F4 : Split the current view. If the caret is currently
           on a line containing a PROCedure or FuNction call,
           the new view will be positioned to the appropriate
           DEF line.
      F6 : Set the selection to include the caret line.
Shift F6 : Select the current block of code or REMs
      F7 : Initiate an incremental search backwards.
Shift F7 : Find/Replace previous.
Ctrl  F7 : Find first/Replace to the first.
      F8 : Initiate an incremental search forwards.
Shift F8 : Find/Replace next.
Ctrl  F8 : Find last/Replace to the last.
      F11: Delete from the caret to the end of the line.
Shift F11: Delete from the start of the line to the caret.
Ctrl  F11: Clear the current line of text.

Shift-Ctrl Fn (where Fn=Function key 0 to 11): Perform a macro.
           Note - Function key 0 is the Print key.

Miscellaneous Keys

The Enter and Insert key actions may be reversed with a
setting in the profile. In "Edit" mode:
Enter    : Splits the current line at the caret.
Insert   : Inserts a blank line following the caret line

The Copy and Ctrl Copy key actions may be reversed with a
setting in the profile. In "Edit" mode:
Copy     : Deletes the character to the right of the caret.
           If the caret is after the last character in the
           line, the following line is wrapped back.
Ctrl Copy: Initiates a copy sequence - see that section for
           more details.

Escape   : If no other condition applies (as mentioned
           elsewhere in this document), Escape cancels all
           changes to the current line (undo).
Delete   : Deletes the character immediately to the left of
           the caret. If the caret is in column 1, the current
           line is wrapped back to the end of the previous one.
Tab      : Move the caret to the next indent column or tab
           stop depending on the profile setting.
           If the caret precedes the text on the line, the
           text is moved independently to its next tab stop.
Shift Tab: Move the caret to the previous indent column or
           tab stop.


-- Macros

DBEdit supports keyboard macros via the use of the function
keys as set by *SetMacro Key$n commands. DBEdit allows the
editing of the macros from within the editor, but these
macros are not saved across sessions.

It is a simple matter to include the relevant command in the
!BOOT or !RUN file so the editor has permanent macros. Click
on the "Copy" icon within the Set Macro box. This outputs (at
the caret) the command required to set the macro up each
session. The caret positioning characters are not supported
by this function but these can be added afterwards.

Shift-Ctrl Print is macro 0, and Shift-Ctrl F1..11 are macros
1 through 11.

To add new macros, or modify the existing ones, open the
"Macro" option of the Icon bar menu. Enter a macro number
from 0 to 11 (or press the equivalent non-shifted function
key) to load the current definition, then change as required.
At any time, click on "Okay" to update the macro, "Play" to
use the macro, or "Cancel" to restore the previous definition.


-- Markers

Ctrl P can be used to set two markers within the file. Each
time a marker is set, it replaces the marker not used last
time.

Ctrl L is used to find the markers. Press once to go to the
oldest marker, then press again to toggle to the other one.
The toggle action continues until a new marker is set.


-- One Key searches

One Key searches are a very neat way to find unique strings
within the source. Using the "current word" wildcard allows
a search string to be found that includes the word that the
caret is on. One Key searches find the first occurence of the
string within the file.

The two default search strings provided allow the finding of:
1. The PROCedure/FuNction definition called at the caret.
2. The assembly label as referenced by the word where the
   caret is.

Note that the "current word" wildcard may only be used in
One Key search strings. The wildcards available for the other
find functions are also available to the One Key search
strings.

Use Ctrl B to return to where the One Key search was
initiated.


-- Selections

The standard Wimp selection functions are available both from
the menu and from the keyboard. Included is the ability to
move or copy a selection from one window to another (even if
the windows contain different files).

As this editor has been written primarily for BASIC, a line
based interpreter, it allows selections on a line basis only.
This makes for very fast selection of code to be moved or
copied about.

The selection may be retained or released after a Copy or
Move action depending on the setting of the "Keep Select"
flag in the profile box.
This flag may also be toggled by pressing Ctrl K.

One extra feature of the keyboard shortcuts, not normally
available in Wimp editors is the use of F6 or Ctrl A to mark
the current line, and if a selection already exists, it is
extended, or reduced to encompass the current line. In effect,
these keys mimic the action of the Adjust mouse button.

It is also possible to select whole blocks of code with one
keystroke.
Any BASIC construction is selected simply by putting the
caret on the first line of the block and pressing Shift F6.
The quick selections include all the standard blocks such as:
IF...ELSE...ENDIF, REPEAT...UNTIL, DEF PROC...ENDPROC etc


-- Undo

Undo is invoked from the "Misc" submenu or via Ctrl O. Each
line change that occurs within DBEdit is saved within the Undo
stack and can be independently restored. Whenever the Undo
box is opened, the before image of the most recently changed
line is shown, and the changed version is highlighted within
the edit window. Click on Undo to put the before image back
into the code. There is one undo stack per file.

As the Undo position is a line offset, there may be occasions
when the caret is not correctly positioned to restore to
the right line. Therefore, while the Undo box is displayed
you may use any caret positioning keystrokes before restoring.
Note that this also allows you to replace any file line with
one from the undo buffer.

Next and Previous can be selected to cycle through the old
versions of lines currently held in the Undo stack.


-- Undelete

Undelete is also invoked from the "Misc" submenu. This
function allows you to restore the most recently deleted
selection. Upon choosing the option, an Undelete box will
be displayed and the caret will be positioned to the line
where DBEdit assumes you wish to restore to. Select Insert to
restore the text, or Cancel to exit the Undelete function.

As the Undelete position is a line offset, the caret may not
always be correctly positioned to restore to the right line.
Therefore, while the Undelete box is displayed you may use
any caret positioning keystrokes before restoring.
This also allows you to do "cut and paste" editing.

The size of the "Undelete" buffer can be set via the system
variable DBEditDel$Buff. Undelete is turned off if this
variable has a value of zero.


-- WildCards for Finds

DBEdit supports four wildcards which may be used in search
strings and for the Index function. The actual character that
represents the wildcard function may be set at any time (and
saved permanently with the profile), but there are defaults
as shown below.

[?] "Match any one character"

This wildcard may be used to match exactly one character
within the file.

[*] "Match 0..many chars"

This wildcard matches any number of characters on the current
line in the text. Its main use is to find two specific strings
anywhere on the same line.
The second use of this character is for including the "rest
of the line" in a replace operation. Matching REM* will mean
the replace wildcard |1 will contain the rest of the line.
See that wildcard for further details.

[$] "Match 0..many spaces"

This wildcard allows fuzzy matching of sequential strings
where no, one, or multiple spaces may separate the parts. To
select matches with 1..many spaces, use " $".

[<] "Match start of line"

This wildcard makes it easy to test for strings at the start
of the line.
The wildcard must be the first character of the search string
or it will be treated as a normal character (unlike the other
wildcards).

You can use this wildcard with a replacement string of REM to
prevent a selected block of code being actioned, and <REM
replaced with nothing to remove the REMs again.


-- Wildcards for One Key

One Key search strings may include any of those available for
Finds, plus the following:

[&] "Current word"

This wildcard is replaced by the word containing the caret
before the search commences.


-- Wildcards for Replaces

There are two wildcards available for use within the replace
string. These allow all or parts of the found string to be
put back into the resultant line during the replace operation.

[&] "Found string"

Use this wildcard when you wish to append new characters to
existing text. It represents the entire string within the
current line that matched the search string (including text
that matched any wildcards).

[|] "Ambiguous part (n)"

This wildcard gives the powerful ability to pick and choose
parts of the found string. The ambiguous sections of the
found string are all available (ie those that matched any of
the Find wildcards ?, *, or $).
Ambiguous sections 1 to 9 can be recovered.


--------------------------   END   ---------------------------