The C Users' Group Library 1994 August/wc-cdrom-cusersgrouplibrary-1994-08.iso/vol_100/157_01/qedpc.doc

Text File | 1987-10-12 | 23KB | 510 lines

QED VERSION:        1.22
LAST COMPILE DATE:    15 DECEMBER 1987
DOCUMENTATION DATE:    13 APRIL 1987
PCDOS VERSION:          2.1 AND HIGHER
AUTHORS:              Nigel Gilbert and James Haefner

---------------------------------------------------------------------
TABLE OF CONTENTS

I.    GENERAL DESCRIPTION
II.   HOW TO RUN QED WITHOUT READING THE MANUAL
III.  COMMAND LINE INVOCATION
IV.   DEFINITION OF CONTROL KEYS
      A.  CURSOR MOVEMENT
      B.  BLOCK MOVES (Save, Exit, Move text)
      C.  DELETIONS
      D.  "QUICK" MOVES (Find/Alter, Defaults, File manipulation)
      E.  PARAGRAPH REFORM
      F.  VERSION DOCUMENTATION
V.    TRICKS
      A.  UNDO
      B.  INSERTING ESCAPE SEQUENCES INTO TEXT
      C.  EDITING SEARCH LINES
      D.  DEFAULT FILE EXTENSIONS
      E.  JUMPS
      F.  MARKING TEXT
VI.   BUGS
VII.  TABLE OF CONTROL CHARACTERS
---------------------------------------------------------------------

I.   GENERAL DESCRIPTION

     QED is a public domain editor originally written in C by
Nigel Gilbert of England.  His version was written in BDS C
(trademark) for microcomputers running CP/M versions 2.x and 3.0.
The original Gilbert version is available from the C User's Group
(McPherson, Kansas).  I (J. Haefner) made major modifications to
this original code for CP/M, ported these modifications to MSDOS and
PCDOS.  QED comes in a variety of flavors depending on the target
computer; QEDPC is the version that runs on IBM-PCs and compatibles.
Below, QED and QEDPC are synonymous.

     QED is a full-screen editor that it attempts to duplicate the
user interface of WordStar (tm) as closely as possible, with
"improvements" as I have seen fit.  (As a full- screen editor, it
bears no resemblence to line editors such as EDLIN or SOS.)  There
are no "modes" in the sense of some screen editors in which one must
explicitly choose a "command" mode or a "input" mode.  In QED, one
is always in an "input" mode; commands to the editor that are not
text to be inserted in the file are keyed in as control characters
(i.e., characters transmitted by typing the "control key" and
certain alphabetic and punctuation keys simultaneously, usually
symbolized as ^x, where x is a character, e.g., ^C).

     QED is intended primarily as an editor for creating programs or
keying in numerical data.  As such, it has some features of interest
to programmers and lacks many features of word processors.
Obviously, it can also be used to create files of text to be sent to
a text formatter such as RUNOFF.  For the programmers, QED has
auto-indent, "jump to" a line, an extensive list of command line
options, search and replace, reformatting of indented program text,
and an "expert" mode.  It also has automatic word-wrap at a
prescribed screen column setting and the ability to reform
paragraphs to fit within a prescribed column setting.   It lacks,
alas, right justification, and printing formatting facilities.  QED
produces "straight ASCII" files, i.e., files containing no special
formatting codes or printing control character sequences.  As a
result, QED is well-suited for creating files required by other
applications or programs (e.g., OMNIPLOT plotting package, data
entry for statistical programs, etc.).


II.  HOW TO RUN QED WITHOUT READING THE MANUAL

     1.   QEDPC occupies only 37K of disk space, so it can easily
reside on any disk, drive A or B.

     2.   If you are a beginner, you will want the non-expert
mode and the on-screen help to be permanently displayed.
Assuming this, invoke QEDPC to begin a new file with:

          A>QEDPC -E -V

(The "A>" is the PCDOS prompt indicating drive A as the default
drive, of course.)  This will present you with a status line at the
top of the screen, about 6 lines of help messages, and the cursor
over the point at which text may be inserted.

     3.   Insert text by typing any of the printable ASCII
characters.  Hit the "RETURN" key at the end of each line (no
automatic word-wrap).

     4.   To save the text as a file type ^K (CTRL and K
simultaneously).  This will prompt you with a verbose, but
informative instruction.  To save the text and leave QEDPC, respond
with Q, then W (after the prompt), then the file name (after the
prompt), then E (after the prompt).  In short, the sequence is
^KQWE.

     5.   To edit an existing file invoke QEDPC this way:

          A>QEDPC filename -E -V

          This will display a message reminding you of the name
of the program you just typed, followed, after clearing the
screen, by the first 23 lines of text of the file.  QEDPC cannot
distinguish text files from non-text files; therefore, garbage
will appear if you attempt to edit an EXE file, or any other non-text
file.

     6.   To move around in the file, type the control characters
as indicated on the on-screen help (^QO), and as more fully described
below (in the manual!).  QEDPC has no "overwrite" mode, one is
always inserting text, pushing existing text ahead of the cursor.
Explicit deletion is required to remove this text.  Exiting the
editing session is the same as above.


III. COMMAND LINE INVOCATION

     The official syntax of QEDPC 1.22 is:

QEDPC [-Jn -A -B -L -H -R -Mn -Tn -S -U -V -E -X -Dd [filename1 [filename2]]]

"[]" indicates optional input.  "Filename1" is an optional file
which QEDPC is to read in and "filename2" is an optional file to
which QEDPC is to save any editing changes made.  If "filename2" is
absent, "filename1" is used.  Each letter in the command line is an
option that configures the "context" or "environment" of the current
editing session.  They have the following meanings and defaults []:


          -Jn:  Jump to line n [1]
          -A :  Autoindent on carriage return [YES]
          -B :  Make backup file on exit (filename.bak) [YES]
          -L :  Show line and column on statusline [YES]
          -H :  Horizontal scroll entire screen [NO]
          -R :  Read entire file on initial load [YES]
          -Mn:  Margin (right) set to n [255]
          -Tn:  Set tabwidth to n [4]
          -S :  Strip trailing blanks and tabs [YES]
          -U :  Update version and date [YES]
          -V :  Display onscreen help [NO]
          -E :  Expert (terse) mode [YES]
          -X :  Warm boot on exit [YES]
          -Dd:  Drive d for temporary paging files [current]

Options and filename1 may occur in any order; filename2 must
follow filename1.  Upper and lower case may be used in any
combination.

     Examples:

     QEDPC -j400 -e -T8 FOO.BAR foo2.bar

     This will invoke the version of QEDPC, will turn the expert
mode off (-e), set the tabs to 8 spaces (-T8), read from FOO.BAR and
write to FOO2.BAR, and jump to line 400 (-j400).

     QEDPC

     This will load QEDPC and present the user with a blank screen
for data input.


IV.  DEFINITION OF CONTROL KEYS

     A complete map of the functions of all control keys (^x)
is at the end of this documentation.  Two (^Q and ^K) have no
immediate effect, but prompt for more command input (see below).
Typing ESC (escape key) at a prompt will cancel the request and
usually returns the cursor to the text being edited.

     A.   CURSOR MOVEMENT

     Cursor movement is controlled using control characters.  The
association of function with control key follows, in general, the
pattern of WordStar (tm).  For the most part, the function of
control keys reachable from the left hand is identical to
WordStar:  the keys A-E-F-X form a diamond where the top of the
diamond produces movement upwards, the left-side produces
leftward movement, and so on.   Vertical scrolling which leaves
the cursor in place is implemented via ^W (scroll up through
file) and ^Z (down).  ^Y and ^V moves the cursor to the top and
bottom, respectively, of the screen.  ^U and ^B moves the cursor
to the top and bottom, respectively, of the file.  Thus, for the
left side of the keyboard there exists a relatively uniform and
mnemonic mapping of key position and cursor movement.

     QEDPC accepts lines up to 256 characters; longer lines are
truncated.  Lines with characters off the screen have a high-
lighted ">" in the last column.  Horizontal scrolling to columns
greater than the screen width of the terminal occurs in two
modes:  only the present line is scrolled or all lines on the
screen are scrolled horizontally.  The current mode is changed
with a toggle altered in the editing context option (see below).
The default (scroll current line only) may be altered at the
command line invocation of QEDPC.

     On the right-hand-side of the keyboard, there is a less
suggestive mapping.  ^O and ^P move the cursor to the left and
right, respectively, end of the current line.  ^I, ^N, and ^M
implement standard ASCII interpretations of the control
characters:  tab, line feed (new line), and carriage return.

     QEDPC implements most of the important, common block movement
functions:  global search and replace, write block to file, block
movement, block deletion, and block copy.  In addition, the lines
of a block may be "shifted" with tabs, spaces, or deletions.  This
is a boon to programmers using structured languages, since blocks
may be explicitly indented using this feature.  The block mode is
also used to exit the editor and save, in accordance with the
WordStar convention.

     Block activity is initiated as in WordStar with ^K.  If
"expert" mode is off, verbose prompts will appear on the screen;
if "expert" mode is on, only the set of permissable letters is
shown for prompt.  The allowable responses are mnemonic and are
summarized at the end.

     To define a block of text, place the cursor at the line from
which the block definition is to be initiated (may be the bottom
or the top of the block).  (Block definition is by line, not by
character as in WordStar, thus, only blocks of entire lines may
be defined.)  Type ^K, at the prompt make a choice of operation
to perform on the block (copy, move, delete, etc.) and, at the
prompt, use the cursor control keys to move the cursor to the
last line of the block.  When the last line is defined, hit
<RETURN> and the function will be performed.  Typing <ESC> (the
escape key) will cancel the block operation at any point during
prompting.  If the "shift" operation is chosen, then, after the
block is defined, another prompt requests an editing function to
be performed on all lines in the block (e.g., insert tabs, delete
characters, etc.).  When <RETURN> is hit following input of the
editing operations, then all lines in the block are subjected to
those operations.  In this way, a block of lines may be easily
indented for formatting structured programs.

     Other block functions are self-explanatory.  A rapid method
to save a file and return to PCDOS is invoked by typing ^KX;
analogous to WordStar.  A second quick backup method is described
below in subsection D.  To write an edited file to disk and open
another file for editing requires the following key strokes:
^KQWA.

     C.  DELETIONS

     There are several ways to delete text.  ^G deletes the
character under the cursor; DEL deletes the character to the left
of the cursor.  ^T deletes from the cursor position to the end of
the current word.  ^QY deletes to the end of the line on which
the cursor is currently lying; ^\\ deletes the whole thing.  The
sequence  ^KBD allows the definition of a block to delete.
BACKSPACE (^H) is synonymous with ^S: move the cursor one
character to the left.

     D.  "QUICK" MOVES INCLUDING SEARCH AND ALTER

     Following WordStar ^Q does "quick" movements.  To find text
type ^QF, to find and alter text type ^QA.  (^L while inserting
text (not after ^Q) will repeat the last search or alter
command.)  If the user chooses not to be queried for alter
verification, QEDPC will not show the changes as they are made.  If
this is desired, use the <V>erbose option after the new text string
is supplied.  To toggle the onscreen help type ^QO.  ^QL turns
off the statusline at the top of the screen except the filename.
This speeds screen display.

     In addition, ^QK clears the screen and displays the "context"
or default settings for some variables of the current editing
session.  Among these are tab settings, whether a backup file will
be saved, whether expert mode is on or off, the state of the
onscreen help menu, the current maximum number of lines of text that
may be edited, etc.  A prompt is issued to instruct the user how to
change any of these variables.  In addition to altering variable
values, ^QK followed by "F" (for "Files"), will clear the screen and
prompt the user for input to erase files, change the name of the
edited file, list the directory, change the path, etc.

     Quick backups of the currently edited file can be made via ^QB.
This command concatenates the filename to a string which is the
directory in which you wish to save the file.  For example, if the
current default quick backup directory is the string "B:\\" (i.e., the
root directory of drive B) and the current file is "foobar.c", then
"^QB" will produce the message "Saving B:\\FOOBAR.C" and save the file
in the root directory of B.  The directory string, which may be any
legal PCDOS pathname, is specified with the "D" option of the
editing context screen (^QKD).

     E.   PARAGRAPH REFORM.

     QED has automatic wordwrap at a prescribed screen column set by
typing ^QK (editing context).  There are two mechanisms for reforming
a paragraph.  The first, using ^QP (for "quick prettification of
paragraph"), will reform from the current line to either the next
empty line, or the next line beginning with white space (space or
TAB), or the end of the file, whichever is encountered first.  The
second method is to define a block of text (via ^KB) and choose the
"<R>eform" operation.  This method permits multiple paragraphs to be
formatted.

     To disable automatic wordwrap, set the right margin (^QKR) to
255.

     F.   VERSION DOCUMENTATION

     QEDPC can document the version number and date and time of the
last save operation for the edited file.  This information is stored
as the first line of the file as a "comment".  The user must insure
that the appropriate comment delimiters are used.  For example,
WordStar and some other text formatting programs use two periods,
"..", to indicate comments.  Each programming language has its own;
FORTRAN uses "C" or "*" in column 1; C uses "/*" and "*/" to indicate
the beginning and end of comments; standard PASCAL uses "(*" and "*)"
for the same purpose.

     This feature may be disabled via ^QKV or "-U" on the command
line when initially invoking QEDPC (see section III above).


VI.  TRICKS

     A.   UNDO

     QEDPC has two rudimentary mechanisms to "undo" or retract the
last editing command (e.g., delete a word).  Provided the cursor
has not moved from the vertical screen row on which the editing
operation was performed, ^_ (CTRL-underscore) will undo the
operation.  A deleted line (i.e., ^\\) can be recalled if the
cursor has not left the vertical screen row on which the deleted
line lay, by the following sequence:  "^N^_" (i.e., make a
newline (^N), then undo the line deletion operation [^_]).

    The second method is more direct.  A complete deleted line (via
^\\) or partial deleted line (via ^QY) may be inserted below any other
line by using ^^ (i.e., control-shift-6).

     B.   INSERTING ESCAPE SEQUENCES INTO TEXT

     QEDPC has a magic key for inserting any unprintable character
into the text file.  While in the insert mode (i.e., not
responding to a prompt), typing the escape key (<ESC>) will
transform the next character between 40 hexadecimal (ASCII
character "@") and 5F hexadecimal (ASCII character "_") into the
corresponding control character.  For example, the sequence
"<ESC>L" will imbed ^L in the text, "<ESC><ESC>" imbeds "^["
(escape) in the text.  Control characters in text files are
displayed in highlighted or inverse video by QEDPC.  The primary
application of this facility is to embed sequences of control
characters to manipulate printers.  If the proper sequences are
embedded at the beginning of the file, the printer may be
initialized.  Inserting ^L into the text will force a form feed
on many printers, and so on.

     C.   EDITING SEARCH STRINGS

     Simple editing and replaying of search strings may be
performed.  The last search strings is saved in a buffer; this
may be displayed at the "Find?" prompt for the search or alter
command by typing ^L.  If the buffer is empty, typing ^L will
embed ^L in the search string.  For programming simplicity, <ESC>
terminates the input of the search string, and, thus, cannot be
directly searched for.  A kludge is implemented to work around
this: "^]" will be translated to "^[" in the search string.

     D.   DEFAULT FILE EXTENSIONS

     The file extension of the file invoked from the command line
is saved and used as a default.  Subsequent requests for files
need not have the extension, if the default is desired and no
other file exists on the sub-directory with the same filename and
a null file extension.  The default file extension may be altered
during an editing session by requesting a file using an explicit
file extension.  To denote a file with no file extension, use a
dot following the filename (e.g., "foobar.").

     E.   JUMPS

     Lines to jump to can be defined on the command line invoking
QEDPC or during editing.  ^J will invoke a prompt requesting the
line.  Responding with a number will move the cursor to that
absolute line.  If the line number is greater than the number of
lines in the file, the cursor moves to the end of the file.
Responding with a "+" or "-" followed by a number, will move the
cursor by those number of lines below or above the current line,
respectively.

     F.   MARKING TEXT

     A line of text may be marked and jumped to quickly by the
following trick.  Type ^J, followed by <RETURN> or <ESC>.  This
sets the current line number to the line to jump to.  Leave the
line, do editing, then type ^KJ, and the cursor will move to the last
defined jump line number.  If lines are deleted or inserted
following defining the line to jump to, then the cursor will not
return to the original text.  ^KJ only returns you to the last
defined line number, or the end of the file if the line number does
not exist.   For example,

  ... editing ...     /*now doing some editing */
  ^J<RETURN>          /* define jump line number to current line */
  ^U                  /* go to top of file */
  ... editing ...     /* more editing here */
  ^KJ                 /* jump back to previous line number */


VI.  BUGS

     1.  Undo works only if the cursor remains at the same vertical position.
         (Use ^^ to insert deleted text.)
     2.  Marking text returns to the original line number, not
         necessarily the original text.
     3.  Text marking for one line only.


VII. TABLE OF CONTROL CHARACTERS

    ^@:  No edit function, lead-in character for some terminals
    ^A:  Move cursor left one word.
    ^B:  Move cursor to bottom of file
    ^C:  Move cursor down one page
    ^D:  Move cursor right one character
    ^E:  Move cursor up one line
    ^F:  Move cursor right one word
    ^G:  Delete character under cursor
    ^H:  Move cursor left one character
    ^I:  Tab
    ^J:  Jump.  Displays more options.
         +/-n:  jump n lines down or up respectively
         n:     jump to line n
    ^K:  Block moves.  Displays more options:

         Q:  Quit.  Displays more options (<> indicate possibilites):

                <W>rite to a file.  Displays more options:
                    <E>xit to PCDOS
                    edit <A>nother file
                    <R>eturn to the file being edited
                <A>bandon the current edited file.  Displays options:
                    <E>xit to PCDOS
                    edit <A>nother file
                    <R>eturn to the file being edited (cancel abandon)
                <R>eturn to the file being edited.

         X:  eXit to PCDOS after saving the file
         R:  Read a file, insert at current cursor position
         J:  Repeat jump to last "jump to" line number
         B:  Block moves.  Displays more options:
             <M>ove a block of text
             <C>opy a block of text
             <D>elete a block of text
             <W>rite a block of text to a file
             <P>rint a block of text
             <S>hift a block of text with editing keys
             <R>eform a block of text to have current right margin

    ^L:  Repeat last search or alter
    ^M:  Create new line behind cursor (cursor on new line)
    ^N:  Create new line ahead of cursor (new line below cursor)
    ^O:  Move cursor to left end of line
    ^P:  Move cursor to right end of line
    ^Q:  Quick moves.  Displays more options

         F:  Find.  Displays more options:
             <B>ackward search, up through file
             n: (number) of items to skip
         A:  Alter.  Displays more options:
             <B>ackward search, up through file
             <G>lobal search from beginning of file
             <T>o end of file from current line
             <W>ithout asking for verification or showing changes
             <V>erbose, show changes as they are made without verification*
             n: (number) of replacements
         P:  prettify current paragraph
         Y:  Delete to end of line
         L:  Toggle statusline ON/OFF
         O:  Toggle Onscreen help menu ON/OFF
         K:  Show editing context.  Displays more options:
             <F>ile context.  Delete files, change names.
             <A>uto indent toggle ON/OFF
             <B>ackup file toggle ON/OFF
             <T>ab length (number)
             <D>efault quick backup directory string*
             <S>trip trailing blanks toggle ON/OFF
             <R>ight margin is n
             <L>ine:column display toggle ON/OFF
             <H>orizontal scroll toggle whole page/current line only
             <E>xpert mode toggle ON/OFF
             <O>nscreen help toggle
             <V>ersion update toggle ON/OFF

         B:  Quick backup of edited file to another directory (see above)*

    ^R:  Move cursor up one page
    ^S:  Move cursor left one character
    ^T:  Delete to end of word under cursor
    ^U:  Move cursor to top of file
    ^V:  Move cursor to bottom of screen
    ^W:  Scroll up, leave cursor on current line and column
    ^X:  Move cursor down one line
    ^Y:  Move cursor to top of screen
    ^Z:  Scroll down, leave cursor on current line and column
    ^[:  ESCAPE, next character is embedded control character
    ^\\:  Delete line on which cursor resides
    ^]:  Pseudo-escape in search strings
    ^^:  Insert deleted line at current line
    ^_:  Undo last edit if vertical screen position of cursor unchanged

-----------------------------------------------------------------------
* This item is not in the CP/M version.