ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/KAYPRO/OUTLINER.LBR/OUTLINER.DZC/OUTLINER.DOC

Text File | 2000-06-30 | 19KB | 363 lines

                              O U T L I N E R

                                release 1.0

                           an Outline Processor
                                  U&U Ltd

                              Copyright 1987
                              David A. Usher
                            62 Turkey Hill Road
                            Ithaca, N.Y.  14850

  (You may use or copy the program and documentation, but not sell them)


What it is:

     Outliner  is  an outline processor,  that is it can be used  to  write
outlines  or  organize ideas with a minimum of fuss.    I have used it  for
preparing agendas,  research seminars, and outlines for papers.   This is a
no-nonsense outliner,  with streamlined editing and few  restrictions,  but
without some of the bells and whistles.

What it runs on:

     The program was written for a Z80 and CP/M 2.2,  with 64K of RAM.  The
version  here ("OKP.COM") will run on a Kaypro with video attributes  (e.g.
the 2x).    The TPA should be free up to C350H.    I have compiled versions
for  other Z80 computers,  including one that will run with a terminal that
does not have line-insert/line-delete.


HOW TO GET STARTED - A SHORT TUTORIAL

     Anyone  with  a  working knowledge of WordStar will have  very  little
trouble  learning to use this program;  many of the commands are the  same.
Before  starting this brief tutorial,  please make sure that you have  some
free  space on your disk (about 30K bytes should be enough),  and that  the
following files there:

OKP.COM        (The Outliner program)
TEST.OTL       (A practice outline.  All outlines produced by Outliner have
               the extension .OTL)
COMMANDS.OTL   (An outline file that contains a list of all the commands)
TODISK10.COM   (A utility file)


     Run  Outliner by typing OKP followed by a carriage  return  (CR),  and
clear  the sign-on screen by hitting the space bar.   You are now presented
with  a menu.   Choose "C" ("Create a file"),  and it will ask you for  the
name of the outline file that you wish to create.   Type in the name "TINY"
followed  by CR.    You do not need to type in the extension (.OTL) as that
will be added automatically.

     Note  that the top line of the screen  shows the name of the file  and
the  number of free lines left (222),  and it reminds you that that  insert
mode is on.   Verify that typing ^V (control V) turns insert mode off,  and
that typing ^V again turns it back on.

     Now type the following text (leaving out the quotation marks):

"This is the first entry in my outline, and it is at level 0."

     If  you  make  a mistake in typing this line,  you  can  use  familiar
WordStar  commands  to edit out the mistakes:  ^G deletes the character  on
which the cursor is presently sitting,  DELETE deletes the character to the
left  of the cursor,  and ^T deletes the word that is to the right  of  the
cursor.    The  WordStar cursor movement commands have their usual  meaning
(^S move left one space,  ^A move to start of word left,  ^D move right one
space, ^F move to start of word right, ^E up a line, ^X down a line).

     Follow  the text with a carriage return (CR).    Note that the line is
now  preceded  by  a minus sign "-".    This is an  entry  at  the  highest
possible level (level 0).    The cursor will now be waiting at the start of
the  next line down.    Now press TAB once.    The cursor should indent  by
five spaces.   Type:

    "This is the second entry of my outline.  It is at level 1, and I am
     going to go on typing until it has to wrap around."

     Notice  that the text wraps around automatically,  and that both lines
of  this entry are indented by  the same amount (5 spaces).    Now type CR,
and  note that the minus sign on the first line is replaced by a plus  sign
"+";  this tells you that the first entry (level 0) is followed by an entry
(level 1) of lower importance.  If we regard the entry at level 0 as a main
heading, then the entry at level 1 can be thought of as a sub-heading.

     Now  press  TAB twice,  and note that the cursor has indented  by  ten
spaces, then type:

          "This is the third entry, and it is at level 2."

     Now  press CR,  and note that both entries #1 and #2 are  preceded  by
plus  signs.    Evidently entry #3 is counted as a subheading to entry  #2.
Let's type one more entry;  first hit TAB just once (if you hit it too many
times,  and  you have not yet entered any text,  you can start again at the
left margin by hitting DELETE,  or you can move it five spaces to the  left
every time you hit ESC).   Then type:

     "This is the fourth entry, and it is at level 1."

     Follow  this with a CR.    This is a good time to save your  work,  so
type  ^KS  (the control key does not need to be held down  for  the  second
letter).    After the disk save,  the cursor will wait exactly where it was
before we typed the ^KS.

     The text window of the screen should look like this:

+ This is the first entry in my outline, and it is at level 0.
     + This is the second entry of my outline.   It is at level 1, and I am
       going to go on typing until it has to wrap around.
          - This is the third entry, and it is at level 2.
     - This is the fourth entry, and it is at level 1.


     It is convenient to think of the second,  third and fourth entries  as
being "attached" to the first entry, because they follow it in the outline,
and they are all of lower level or importance  (i.e.  level 0 is a "higher"
level  than level 1,  which in turn is higher than 2 etc;  the lowest level
allowed by the program is 5).    By a similar argument,  the third entry is
attached  to  the  second.    However,  the  fourth  entry  is  of  greater
importance than the third,  and of equal importance to the second, so it is
not attached to either.

     This  becomes  important when you want to move parts  of  the  outline
around.    We  will practice this a little later,  but for now just try the
following:  use ^E to step the cursor up line by line, until it is anywhere
in  the first entry (or go there at once with ^QR).    Now type ^KI  ("mark
entry"),  and note that the first entry becomes "highlighted",  but its "+"
flag  is still displayed in normal intensity.    This entry,  BUT  NOT  ITS
ATTACHED ENTRIES,  is now "marked".   Type ^KH and the entry will return to
normal.   Now type ^KB ("mark entry plus its attached subsidiary entries"),
and  note  that  not only does the first entry (AND its  "+"  flag)  become
highlighted,  but also ALL OF ITS ATTACHED ENTRIES.    I will refer to this
as a marked block of entries.    Unmark the block with ^KH,  and use ^X  to
step  the  cursor  down until it is anywhere in the  second  entry  (either
line).    Now  type  ^KB  and note that only the second and  third  entries
become marked.    As we will shortly see,  you can  move,  exchange,  copy,
delete, or change the level of marked blocks, even though all of the marked
entries may not be visible (e.g. if some have been hidden by collapsing the
outline).


A PRACTICE OUTLINE

     Now  let's see why an outline processor is much more powerful than  an
ordinary word processor when it comes to organizing outlines.    To do this
we  will  use the practice outline called "TEST.OTL".    First  close  your
"TINY.OTL" by typing ^KD (save to disk) or ^KQ (abandon), and when the main
menu appears,  choose "D" ("Edit a file").   You will be asked for the name
of  the  outline  file that you wish to edit.    Type in  the  name  "TEST"
followed by a carriage return (CR).    Again you do not need to type in the
extension (.OTL) as that will be added automatically.

You should see the following:

+  Plan of a brief tutorial on how to use "Outliner".
     - The tutorial is in the file OUTLINER.DOC
     + What computers Outliner will run on
     + What other programs are needed
     + How to begin
     - Check operation of cursor controls.
     - Expanding or contracting how much detail of the outline is shown.
     - Adding or deleting text in a presently existing entry.
     + Starting a new entry
     - Marking an entry, or block of entries.
     + Manipulation of entries
     - Saving to Disk.
     - Making a .TXT file that is readable by WordStar.
     - Printing a file.


     (If you do not see this display,  type ^O1 (control O, followed by the
number  1).    If it still does not look like the above,  then the file  has
been altered, but never mind, what follows is still useful).

     This  is  a partly collapsed outline:  all entries below level 1  have
been  hidden.    To see ALL the entries,  you could type ^O5.    This is  a
"global" command, and shows all entries down to level 5.   (If you did type
^O5,  then return to where you were by typing ^O1).   In addition, there is
a  much  more selective operation that you can perform  with  this  outline
processor.    Use ^X to step the cursor down to somewhere in the third line
("+ What computers Outliner will run on"), and type ^J5;  this command also
means  "show down to level 5",  but is a "local" command,  i.e.  it applies
only  to  entries that are attached to the entry in which  the  cursor  was
sitting  when  the ^J command was issued.    You should now see  some  more
detail (although ^J5 is a bit of an overkill, because the lowest level that
was  hidden  under this entry was only level 2).   If you didn't know  what
absolute level to specify,  you could instead have just typed ^JM,  and  it
would have shown one more level of detail.  ^JL will show one less level of
detail.   Either command can be repeated.    Similar commands are available
for  the  global command ^O;  i.e.  you can give commands either  that  are
relative to what is presently being displayed (^OL or ^OM), or that specify
an absolute level (^K0 through ^K5).

     The  power  of an outline processor comes partly from this ability  to
let you see the big picture,  by hiding distracting levels of  detail,  and
partly from the ease with which you can manipulate sections of the outline.

     Let's do a little manipulation.    Go to the top of the file by typing
^QR,  and  then expand everything (^O5) so that we can see more easily  the
results  of our commands.    Use CR (which steps from anywhere in one entry
to the start of the next entry) or ^X,  to put the cursor somewhere in  the
third  entry  from the top ("+ What computers Outliner will run  on"),  and
then  type ^KB (mark block).    Now use CR or ^X several times to  put  the
cursor  on  the  entry "How to begin".    Note that this  entry  has  three
"attached" entries.   Now type ^KE, and you will find that the marked block
and  the entry  in which the cursor was sitting when the ^KE was typed have
exchanged places.    Note also that the three entries that were attached to
the entry "How to begin" have gone along with their "parent".    They would
have  gone  along  even if they had been hidden.    If  we  had  wanted  to
exchange  the  marked block with JUST the single entry "How to  begin",  we
could have typed ^KI^KE instead of just ^KE.    This may remind you of  the
use of ^KI to mark a single entry, instead of ^KB which marks an entry plus
any entries that happen to be attached to it (visible or not!).

     Instead  of  exchanging two entries or blocks,  you can move a  marked
entry  or block to a new place by moving the cursor to the  desired  place,
and  typing ^KV.     The entry that was previously there gets moved down to
make room.   You do not have to place the cursor at the start of the entry-
that-is-to-be-moved down, just put it anywhere in it.   If instead you type
^KC,  then  a copy of the marked entry or block will be inserted at the new
location,  and the original marked entry or block stays where it  was,  and
becomes unmarked.

     To delete a marked entry or block,  visible or not, type ^KY.  You can
restore  a just-deleted entry or block by placing the cursor where you want
it to appear, and typing ^KG.

     You  can raise or lower the level of a single entry by one level  with
ESC or TAB respectively,  or you can raise or lower a marked entry or block
by one level with ^KM or ^KL respectively.    You can change the level of a
marked  parent  to an absolute level with ^K followed by  a  number.    Any
attached entries that are marked will maintain their relative positions  to
the parent.   Entries will be automatically reformatted to conform to their
new left margin.


DETAILS, DETAILS

     If  you  want to make a change in a previously typed  entry,  just  go
there  and  start  typing or deleting.    New lines will  be  generated  if
necessary,  and  you can use ^B if you need to reformat an entry  manually.
Unlike some well-known outline processors,  you are not limited to one line
for each heading.

     To generate a blank line between two entries,  so that you can type  a
new entry there directly,  sit the cursor anywhere in the second of the two
entries,  and type ^N.    Until the first text character (even a space) has
been  entered  on this now blank new line,  several of the cursor  movement
commands  are INACTIVATED.    This was done to simplify programming,  but I
may change this in a later version.

     When the outline has been saved to disk and is subsequently re-opened,
the  amount of detail displayed will be the same as when the file was  last
saved.

     You  can  generate  a  blank line by typing a  "space"  as  the  first
character  of  a new entry,  and then typing CR or any other  control  that
moves the cursor to some different line.

     There are no restrictions on "skipping" levels,  i.e.  a level 0 entry
could  be followed by one at level 3 etc.   You could start the whole  file
with  an  entry at level 5 if you wanted to,  or exchange (^KE) entries  or
blocks  that are at different levels.    Not all outline  processors  allow
this sort of thing.

     In  the  Outliner program you can add a drive letter  (followed  by  a
colon) before the name of a file.

     When you delete an entry or block of entries, it becomes provisionally
deleted, but any previously deleted entries get permanently deleted at this
point.   Note  that permanent deletion frees up lines,  as measured by  the
"LINES  AVAILABLE" message at the top of the screen,  but the provisionally
deleted ones do not, at least not until they get permanently deleted by the
next  entry-deletion-activity.   A  disk  save will remove  both  sorts  of
"deleted" entry from the saved file.

     I  decided  to  have different menu selections for "Edit a  file"  and
"Create a file" because I sometimes misspell a filename.    When I do  this
in  WordStar  the program assumes that I want to start a new file,  and  it
takes a little while for me to abandon it and have another go.


LIST OF COMMANDS

     To see all the available commands,  run OKP.COM;  at the menu,  select
"D" ("Edit a file"),  and give the filename COMMANDS.    You can then  step
through   and  read  all  the  commands  with  normal  WordStar   controls.
Alternatively,  just  select "P" ("Print a file"),  and print the file out,
specifying down to level 5, with or without the +/- flags as you wish.


WORDSTAR COMPATIBLE FILES

     If  you  want  to  insert an outline that you have  generated  into  a
WordStar  file,  or use WordStar to format an outline for special  printing
needs,  then at the menu,  select "T" ("Make a .TXT file").   The resulting
file will have "soft" CR and spaces within an entry,  "hard" spaces at  the
start  of  an  entry,  and  a  "hard" CR at the  end  of  an  entry.    The
indentation  (when  +/- flags are not included) fits the  WordStar  default
tabs.    This  can  be edited with WordStar.    The original .OTL  file  is
untouched.


IN THE EVENT OF A CRASH

     Together  with  OKP.COM is a program called  TODISK10.COM;   it  is  a
utility  to  save the appropriate part of memory to disk in the event of  a
crash.  At least there is then a chance of salvaging your work.  If you get
an  error  message and it aborts to CP/M,  then if there  is  something  in
memory  that you want,  just type TODISK10 and it will ask for a  filename.
Type  something  appropriate (including the extension .OTL),  and  it  will
attempt to save your work to disk.   If the program had aborted to the menu
instead of to CP/M,  immediately type "X" (exit to CP/M),  and when you get
back to CP/M,  run TODISK10.    I should be grateful if you would note  the
number or letter of any error messages.

     The  "window" on the text of the outline is 20 rows deep.   The top  4
lines of the screen are reserved for messages and for the status line.


     At  the moment there is no "on-line" help file,  although one can  use
^KT  (if one remembers it!) to read in the COMMANDS file,  and then go back
to your own file with another ^KT.

Restrictions:
     One file has a maximum of 222 lines.   Text entry will be frozen if an
     attempt is made to exceed this figure,  but some commands can still be
     given (such as "delete line"!).
     There  is a limit of six different "levels",  level 0 is the  highest,
     and level 5 the lowest.
     At  present there is no error trap if someone types a "word"  (i.e.  a
     string  of text characters that has no spaces in it) that is too  long
     for one line.    Also there is no trap to catch "wildcard" file names,
     please avoid using them.


SOME ADDRESSES

     The  following addresses apply only to release 1.0 of OKP.COM;  all of
these  strings  must  be followed by a $ (except the  string  for  absolute
cursor addressing,  which is followed by the row and column values (with  a
20H offset),  and then a null byte).    The following codes are in OKP.COM,
and are for the late-model Kaypro 2x.

01F0:     Line insert (ESC,E)
01F3:     Line delete (ESC,R)
01F6:     Reverse video (ESC,B,0)
01FA:     Normal video (ESC,C,0)
01FE:     Normal brightness (ESC,C,1)
0202:     "Highlighted" (dim) (ESC,B,1)
0206:     Clear to end of line (18H)
0208:     Clear to end of screen (17H)
020A:     Clear screen, home cursor (1AH)
020C:     String to begin absolute cursor address (ESC,3DH)


     If  you have any trouble with this program,  you could try reaching me
at [phone].

                              David A. Usher