APDL Public Domain 1/APDL_PD1A.iso/textutil/jgpsuite/Docs/JGEdDoc1

Text File | 1993-05-18 | 24.0 KB | 530 lines

.if 0
This is a continuation of JGEdDoc, included by .\ \+JGEdDoc1 when JGPrint/Doc is
applied to JGEdDoc. It lacks prologue directives , and, therefore, JGPrint/Doc
should not be applied directly to it. This note never gets JGPrinted, since 0
after .if is construed as false. It must, of course, always be in the same
directory as JGEdDoc. I have left it as type JGEd, since JGPrint cannot usefully
be applied to it directly.
.fi
.cp 6
.col
|Accessing CLI from the Macroline.

JGEd can access the CLI in extended mode for * commands using */<CLItext>/ (x is
a synonym for *, and saves finger stretch). A failure will be reported. Only
modules and internal commands can be executed.

Remember, F1 in the macroline inserts there the path to the file being edited.

Some JGEd commands duplicate available CLI commands. I have not given a JGEd
command for *Alphabet, since there is no SWI to do it; system Variable Set is
redundant and its absence is no loss; ev<n>, setting JGEd$var, is certainly
needed, as is iv/<system variable>/, which inserts the string value into the
text at the cursor position. I find myself often using dd and ft (qv.).

.if \u10 eq arc
.cp 6
.col
|Filetype

JGEd picks up the filetype of the file it is editing, and puts out an updated
version with the same filetype and the current timestamp. If editing a new file,
it gives it the default type JGEd (currently &203). Files written on the fly by
SaVe, WriteBlock and Automatic Save are similarly stamped. The extended command
ft/<t>/ changes the filetype recorded. <t> can be a filetype name, eg JGEd, or a
number, default style Hexadecimal.

When Acorn allocate me filetypes, it should not be necessary to change any
code; see JGDispute for what will be needed.

.fi
.cp 6
.col
|Line Separators

On input, JGEd recognises any of the four strings <13><10>, <10><13>, <10>, <13>
as a line separator. (It holds each line padded out to wordlength, together with
some structural information.) It picks out the first line separator it
encounters, and uses this to separate the lines of all files it outputs. The
extended commands Line Both, Line Newline and Line Return allow all but the
second to be reset. On a New file, the default is lb.

.cp 6
.col
|Wordwrap and Formatting

Left Margins, Right Margins and Tabs can be Set, and the state display F1+5
displays a ruler based on their settings. The screen acts as a window that
scrolls both vertically and horizontally. The TAB key, in possible association
with SH and CTRL, tabs right and left, without/with adding to/deleting from the
line. TaB is the extended command, to move right inserting spaces, BackTab, to
move left, deleting. Left Tab and Right Tab move the cursor only.
.if \u10 eq arc
 If the cursor is 'after' the rightmost screen character it shows under that
character and does not cause window movement. The caret will appear off-right of
the window as two small dots. Initially, or if the right-margin is screen width,
changing mode resets the right margin to screen width.
.fi
 Words wrap at the right margin. Auto-/No Indentation set new lines below the
first non blank in the previous line, at the left margin. Auto- is the default.
AUtoindent implies that at a newline, the current line\-indentation will be
preserved.

ForMat(f10) reformats lines according to these rules. Format for
jgPrint/CTRL-SHIFT-F10 does not reformat lines that begin with a '.'.

.cp 6
.col
|Character Set

The default character set is bytes 32-126, 128-255. INSERT followed by a number
followed by a non\-digit inserts the non\-keyboard characters in both text and
macro\-line. &+hexadecimal digits is also accepted. The user must define
non\-displayed characters, e.g. 128-159, if these are to be displayed. Numbers
outside the allowable range will provoke a report. CTRL-F10 switches on the
ability to accept bytes 0-31,127. They display as inverse video of the
representation of the byte + 32, except that 127 is shown as inverse ~.

See above for how to redefine the pixel representation of the bytes.

Bytes 9-13 can be inserted during an editing session, but may be interpreted on
reentry after saving as backspace, delete etc. These, and others, may well also
be troublesome on entry to other programs.

(All switches described below can also be set from the JGEd icon bar icon
options menu.)

The characters accepted can  be changed by a switch on the commandline;
.ht 10
.setst :\t:
.makel 10col

.nost
-c \t}The control bytes 0-31 and 127 are allowable ab initio.

.usel base
If during input, a control byte is encountered although -c was not requested,
the user is asked whether she wishes to allow it through as though -c were on
the macro\-line, or to exit. Note that <13> and <10> can be inserted in a line,
but, at present, the line separator rules would, in practice, make JGEd
unsuitable as a binary editor.

.cp 6
.col
|Spelling

JGEd allows David Pilling's Microspell module to be accessed while editing.
sp/<string>/ puts, above the current line in the text, the list of words that
match <string>; these words are made into a block for easy deletion.

Spell-oN and Spell-ofF are accessible as extended commands. Spell-off is
executed on entering and leaving JGEd, and, temporarily, while entering commands
on the macroline.

JGEd will try to load the module from the currently selected directory, the
library or from <jgp$dir>.

For further details see Microspell's documentation. NB It is intended to
replace this with a similar 'speller ' that can be more closely integrated
with JGEd.

.cp 6
.col
|Numerical Calculation

JGEd has a small built-in calculator consisting of a Number register and a
Memory register. The extended command nt transfers the value in the Number
register to the Text.

t=, t+, t-, t*, t\ find the next number, x say, in the Text; the number register
is then set to, respectively:
.col
|x, v+x, v-x, v*x, v/x
where v is the original value in the number register.

l=<n>,....l/<n> are similar, but find the number to act on immediately
following them in the macroLine.

m=,....m/ derives a value for the number register from the Memory register,
which has been calculated from values set in the number register by =m,..../m.
0m clears the memory register.

The commands nr and ns respectively yield, in the Number register, the square
Root and the Square of its previous value.

nx cancels the last operation on the Number register; particularly useful if
there was a number you had forgotten about in the text before the one you really
wanted.

Each time you operate one of the above operations, the value in the number
register is reported, with, if it is a positive integer, the hexadecimal
equivalent (given in brackets). If the memory register is non-zero, its value is
also given. The number of successful operations is quoted, to help if you
want to work out an average.

The "l" commands will accept hexadecimal numerals preceeded by &, so you can
easily transfer between decimal and hexadecimal numerals.

Using pd<n> specifies the number of Places of Decimals that will be available;
the maximum number that can thereafter be put in the registers without
overflow is reported. Initially <n> is set to 2. Anything on the macroline after
pd(n) is ignored.

If the operation you request causes an internal over/under flow, (recoverable)
system messages will report the fact.

.cp 6
.col
|Printing while editing in Non-Wimp state

If Print Block or Print File (/<filename>/) is requested from the macro line the
specified block or file is sent to the printer stream while the editor is
waiting for input from the keyboard; response seems barely affected. If you
attempt to leave JGEd before all bytes have been transferred to the printer('s
buffer), it will wait to return to the commandline prompt. Use Quit and Resume
or save(Z) and Resume (qv.) if there is another file you want to edit. I use my
associated JGPrint to produce print image files for this purpose, rather than
using it direct to the printer. You can also use wb/(printer:/ or sv/printer:/
from the Wimp State, but this may cause delay, or you can drag to !Printers.

.if \u10 eq arc
 Indeed, the application JGPCopy, reached through the JGPrint Icon bar menu, or
implicit for a JGPCopy file, is now usually better than either.

This facility is not available in (wimp-)sharing state; output the file as a
JGPCopy file and double click, or use JGPCopy in the JGEd iconbar menu.
.fi

.cp 6
.col
|Starting

JGEd is intended to be useful in many system contexts; therefore, some of the
information about starting and ending may not be relevant to your needs. Please
skip as appropriate,  certainly on a first reading.

JGEd always requires a filename to edit, and will default to grabbing all store
available as an editing buffer, unless in the desktop, where the amount grabbed
can be set from the icon-bar options menu. If there is a file of the given name, JGEd
will read it into the buffer, and give its length in bytes; otherwise it will
announce that the file is new. If lines are too long (>255 chars), they will be
arbitrarily split and the fact reported; if the file is too long to load in the
buffer, this will be reported; if it is too long to be expanded within the
buffer, it will be reported as truncated. In the desktop, JGEd cannot, in
effect, be used without a filename, but, from the commandline and in scripts, if
a filename is omitted, one will be prompted for, followed by switches.

-b<n> (see below) restricts the editing-buffer size. However, all available
store is, nevertheless, grabbed as addressing space unless the desktop is in
use. 'Extra\-large' files, therefore can best be edited in the absence of the
desktop. (This may be modified eventually.)

Running JGED by dragging a file's icon to the JGEd icon bar icon, or by double
clicking on a JGEd type file icon restricts the addressing space to satisfy the
buffer size (and other switches) set in the icon bar icon menu; initially, a
80k+ buffer possible is provided. If a 0 buffer is requested, the maximum
available will be supplied.

In addition to the commandline switch(options) -b<n> and -c, there are also
available:
.usel 10col

.nost
-p \t}Use the contents of the user variable jged$path as a prefix in the
specification of the file to be edited. Normally this will be a directory path
ending with '.'. JGEd does not use load$path, since it needs a full filename to
save. jged$path is not used for Insert File, Write Block, Save or Q/Z and
Restart. This is not available from the desktop, since the full filename is
provided by clicking. See also the use of F1 in the macroline below.

.nost
-m<n> \t}Open the editing window in mode <n>.

.nost
-v \t}View the file without updating it; attempts to do so will be reported. The
immediate command CTRL-F11 switches View mode off and on.

.nost
-u \t}Cancels the automatic backup facilities (see below).

.usel base
Other Switches are required by the JGP Manager, but need not concern the user.

These switches, and the variables that follow, are particularly useful in
scripts; the option menu provides similar facilities in the desktop.

On entry, the mode is set from jgp$mode if the desktop is active; this can be
cycled through the 16\-colour modes from a window in the options menu of the
JGED icon\-bar icon; the switch -m<n> can be used from the command line. If
this system variable is unset, the mode in which it is called is used. I set
this variable in the !boot file of !jgp, and you may wish to amend my setting,
or do without it.

The left and right margin are set to the full screen\-width, tabs are set every
4 characters, and other default settings are initialised. Note that a character
in the rightmost column does not cause line overflow on the screen.
'wimp\-sharing mode' is entered, if available in this mode.

Second, the system variable jged$init, if set, is put on the macro\-line and
executed with the screen disabled, enabling default settings to be modified.
Third, the system variable jged$line, if set, is put on the macro\-line, but not
executed. Finally, a shortened form of the standard display of the internal
state, which shows the macro\-line, is put above the copyright initialisation
report. (F1+5 gets this report during editing.)

These reports disappear when the first key is pressed. In my scripts, I usually
unset the initialising variables after JGEd returns.

.if \u10 eq arc
In the Desktop, a red caret signifies 'wimp-sharing mode', and a winking cursor
'non\-wimp\-sharing mode'. CTRL-f12 switches between these two, reporting as it
does so. In the former, other desktop processes run concurrently while JGEd
shows the caret, i.e. waits for a key; JGEd's internal concurrent printing
cannot be used in wimp\-sharing mode.

On any MoDe/<n>' command, the right margin, if full width, is reset to full
width. WimpMoDe(n) modifies the desktop mode, but does not change jgp$mode
(determining the initial mode of the editing window). You must set the System
Variable jgp$mode from the commandline, if you want to use other
than a standard 16-colour mode.

.fi
.cp 6
.col
|Writing Blocks, SaVing, Autosave, Backup and automatic backup

There are very extensive backup facilities. SaVe/filename/ is analogous to
wb/fn/, but for the whole text; SHIFT-F9 saves the text to overwrite the
original file. as<n> sets the AutoSave cycle to <n>. (ns cancels, default cycle
512.) That is to say that the text is saved each <n> editing acts in a file
(named Autosave), in the directory of the file being edited. This is intended to
safeguard you if the machine crashes. I recommend reducing 512 if you are
thinking on screen. See below for shareware restrictions.

If you Exit (CTRL-PRINT/zr), any file called Backup> in the directory of the
file you are editing is deleted, and the file you are editing is renamed Backup>
before the text buffer is saved.

The name of the file being written is reported, and when it has all been
written, its length is reported. This message remains for 1 second unless some
other overwrites it.

If a requested file cannot be opened, 'edsave>' in the same directory is
attempted. If this fails, it is reported, and you can try another directory.

.if \u10 eq msdos
In MSDOS, these saving files have the same first part as the name of the file
you are JGEding, but have extensions .bak, .asv and .bkp. Automatic Backup
(below) is to a:\<fdir>\<fname>.<fext>.

.fi
Automatic backup is quite different from the preceeding facilities. Its purpose
is automatically to provide backup on a floppy whenever you exit or quit from a
file you have just saved.

In the Desktop you will be prompted by a window asking you "Backup <leafname>?",
and you should press the buttons to acheive what you want. The facilities are
also available outside the desktop as described below.

Without the desktop, you are prompted Backup?(Y) : after JGEd has completed all
other needed tidying up. If you respond Y/y, assuming jged$bu is unset, you will
be prompted "<diskname>. please; adfs::", and you should type in the name of the
floppy on which you want to backup; there must be, in the floppy's root
directory, a directory of the same name as the one which houses the file you are
editing. You will be presented with the macroline command:
.col
|sv/adfs::<diskname>.$.<dirname>.<filename>/
type RETURN or click select to execute this and return to the desktop.
Alternatively you can edit this extended command before you execute it; you must
include $. in your save string for where you want to save to be remembered. If
you dont want to save, delete out the command, and you will not change jged$bu;
alternatively use a vertical cursor to kill the macroline.

This system variable jged$bu should be of the form
<filesystem>::{<diskname>}.$., where <filesystem> is normally adfs; if defined
it will be used instead of the dialogue as the first part of the save string.

Note that jged$bu is reset after each save from the, possibly edited, sv
command.

Autobackup is set and unset by CTRL-COPY, or unset by the extended command bk.
Default initially is on, but see also the JGEd icon option menu. Bz cancels an
existing backup selection, and, also, proposes backup even if the file has not
been modified.

If you have reached the autobackup prompt, but do not in fact want to do so,
type '.' to get the sv/../, but don't execute it. Remember, F11 empties the
command line, so use it and then type RETURN.

Bug (almost harmless): if the directory into which you propose to save does not
exist, the filer may complain with "channel"; however, the save is the last
thing to be done except for updating jged$bu, so nothing is lost, unless you are
in a script. In my scripts, therefore, I set jged$init to bk, and handle my own
backups. NB if JGEd has left some gunge on the screen, F12 return will clear it.

.cp 6
.col
|Ending

Without leaving JGEd, you can Quit one file and Restart with another, or save
your text and restart with another (zr<f>). (If -p, jged$path is not used.) What
follows applies only to finally leaving JGEd. Automatic backup is performed if
appropriate.

JGEd$var is set on exit to 0 if the text has been not been edited between the
time it was last saved and exiting, whether via Exit(CTRL-f8) or Quit(f9), or
the latent window's menu. If the text has been modified, but you confirm that
you want to quit, JGEd$var is set to 1. However the extended command ev<n> can
set it to n, and this will not be overset by the exit rules. This is intended
for the script user (if <jged$var = 0 then...).

In the commandline, cursor editing is re-enabled and the function key settings
restored to their default value. In the desktop, the original Wimp\-mode is
restored unless a wm<n> macro has been done.

In the commandline, the text background is set to logical colour 0, and the
foreground to logical colour 3. There are extended commands (xc<n> etc.) to
modify these colours , and the extended command sh alters the physical shade
associated with a logical colour; a series of prompts is provided for the
user's convenience.

Lastly, jged$exit is put in the macro\-line and executed. Unlike jged$init,
writing is not disabled. Finally, if appropriate, automatic backup is offered.

From the desktop, colors are unchanged.

.cp 6
.col
|Shutting Up

Shut Up <n> sends a message to JgpCopy to refrain from sending its continue
window for n seconds; 0 is construed as as long as possible. There is a menu
line in JGPCopy's icon bar menu to select continue.

.cp 6
.col
|Boast

The editor one uses most is always the most attractive. Moreover, before one has
internalised an editor's commands, using it has to be a somewhat ponderous
strain. I am a lazy clever fellow, and JGEd should appeal to other such.
Allowing for both my own and a newcomer's natural prejudice, I cite the
following as reasons to investigate and acquire competence in JGEd.

.usel 10col
\u11.The macros that are built up on the macro\-line are the most powerful I
have ever encountered on a micro save for those of EMACS. Moreover they are far
easier to construct than those of EMACS. However, I readily admit that EMACS
allows very much more elaborate and powerful macros.

\u11.The facilities to edit, save and restore the macro\-line are very
convenient. Saving macros in the system variables Key$i enables their definition
and use to span several editing jobs; indeed, the copying mechanism allowing
them to be copied between text and macroline enables their use to span editing
sessions. This makes it more worth building and debugging crafty macros.

\u11.The use of f12 as a single keystroke to repeat a useful macro\-line is
ergonomic and elegant.

\u11.The commands available and their assignment to keys and codes suits me very
well, and, I think, would suit most other people. (I have a few keys unused, and
unlimited extended commands, and would welcome suggestions.) Transposing lines
is, as a programmer, a particular joy.

\u11.Documentation and diagnostics are accessible and comprehensible; a
multi\-window system would, of course, make access to on\-line documentation
more flexible.

\u11.JGEd's syntactic regularity makes it easy to ignore facilities one does not
need, and helps to make acquiring them easier when needed.

\u11.JGEd's capability of sending a file to the printer concurrently with
editing is a great time\-saver, if it is not appropriate to use wimp-sharing
mode in the desktop.

\u11.Treating JGEd and the JGEd/Print handler that manages the icon bar icons as
independent concurrent processes enables JGEd to be available without soaking up
the 100K or so needed for its code when it is not in use. I have met other
applications that are not so considerate.

\u11.The undo facilities much exceed those of many other systems.

\u11.Automatic backup is very valuable when one does not want to bother with
scripts.

\u11.An 80 page Wordstar file came across; including working out what was
required, it took about an hour to undo Wordstar's footprints and recover a
plain ASCII text.

.usel base
Obviously, this is not an editor for those people who restrict themselves to a
dozen Wordstar commands. I sometimes say that it takes up to three years to
become a master JGEd user, but this is more a reflection of the immense power
and flexibility of the macro lines rather than of any difficulty in
straightforward use. I see no reason why a given editing capability should not
be acquired in JGEd in the same or less time than it would be acquired in any
other editor\/wordprocessor; indeed the regular structure and connotative names
may make it easier than for some. The use of JGPCopy, or JGPrint to screen,
obviates a substantial part of the inconvenience of using an editor rather than
a word\-processor which does what it can to provide a WYSIWYG screen display.

.usel base
.cp 6
.col
|Future Developments

"Grovel" would be a complementary alternative to this title, or you may call it
"What's Wrong with JGEd" or "what you Will".

.usel 10col
.nost
\s1=1 \t}JGEd should, like EMACS, allow multiple buffers and screens; the latent
window gives some but by no means all the usefulness of these; as at 4/93
editing within arc desktop windows is planned to be added to the latent window
and the fullscreen window.

\u11.It would be nice to have one window in which one was JGEditing, and another
to which the consequences of passing that text through JGPrint, my system for
laying out text and driving printers, was slaved. It would be even nicer if one
could edit in either window.

\u11.In order to patch code, JGEd could have a macro\-line switch to produce
'pseudo\-lines' of a fixed length that would then be output without line
separators. If it can be done without degrading JGEd's performance in the more
usual case, the display could be adapted to show both chars and hex.

\u11.Repeats are allowable in the macro\-line, but not conditionals; I have an
open mind as to how useful conditionals are, and would be glad to receive
comments.

\u11.Find and count strings could allow regular expression pattern\-matching
rather than requiring an exact match.

Magic characters, edit's response to these, is by no means as flexible as could
be written.

.usel base
An example: a macro to do a 'tab on all lines that begin with a space' can be
built, but not one that distinguishes between lines beginning with a letter and
those beginning with a number. I have rarely had use for this, but would welcome
examples of genuine use. Magic characters could cope with this.

The first three are inter-related, and are also associated with a requirement to
share code between editing instances. (Though I do not think JGEd should become
a module.)

.cp 6
.col
|Filing Systems

JGEd runs from the adfs filing system, the SCSI filing system, and the RAM
filing system. It has not been tested on the NET filing system. It will read
from, but not save to, Archives and Dos disks through early versions of MultiFS.

.cp 6
.col
|Licence

JGEd is copyrighted, and only thieves and knaves use it outside the terms of the
Licences detailed in JGLiceDoc.