HELP ENTER_G Aaron Sloman. April 1986
VED <ENTER> g (LIB * VED_G)
This autoloadable command, based on a suggestion by Josie Taylor,
enables one to have a table of contents in an online documentation file
accessed using VED and to move easily back and forth between the table
and the relevant portions of the file. This is a tutorial file,
formatted to demonstrate the facility. There is a table of contents
below, followed by corresponding sections. Type <ENTER> g then the REDO
button, to see how it works.
More detailed documentation can be found in HELP * VED_INDEXIFY
CONTENTS
--------
-- G_1 Starting up
-- G_2 Going back to the table of contents
-- G_3 Jumping sections
-- G_4 Dummy section
-- G_5 How it works
-- G_6 Marking a section as read
-- G_7 Using INDEXIFY to read HELP files with no index
-- G_8 Using HEADING to insert headings for VED_G
-- G_9 Tailoring VED_G-- G_1 Starting up ----------------------------------------------
The first time you type <ENTER> g in a file it goes to the beginning of
the table of contents for that file. If you do it again while the cursor
is on an entry in the table of contents, then it then goes to the
beginning of the relevant section of the file.
Press <ENTER> g again, to get back to the table of contents. The cursor
will be on the entry for the next section.
Then press <ENTER> g again, or the REDO key, to go to the next section.
-- G_2 Going back to the table of contents ----------------------
If you are not in the table of contents, then <ENTER> g (or the REDO
key, if 'g' is still on the command line) takes you back there, putting
the cursor on the entry AFTER the last one you used.
If you then do <ENTER> g (or REDO) yet again, it takes you to the
beginning of the relevant section.
Try it twice more: once to get back to the table, once to get to the
next section, namely G_3.
-- G_3 Jumping sections --------------------------------------------
You can move the cursor to any desired line in the table of contents and
then <ENTER> g will take you to the appropriate section of the file.
E.g. try getting to section G_5, by going back to the table of contents
(<ENTER> g or REDO key) then moving the cursor to the entry for section
G_5. Then <ENTER> g will take you there.
-- G_4 Dummy section ----------------------------------------------
Nothing of interest here
-- G_5 How it works -----------------------------------------------
The special 'key string' '-- ' is used to indicate section headings.
In the table of contents, it is preceded by a space, at the beginning
of the line. There is no leading space for the section header itself.
If the current line starts with the string preceded by a space, then it
is assumed to be part of a table of contents for the file. E.g. If the
line starts with
' -- '
then <ENTER> g will search for another line containing that string
followed by the rest of the line (minus any trailing hyphens) which will
be assumed to be the title for the relevant section of the file. E.g.
the title for this section does not include the trailing hyphens. It is
'G_5 How it works'
If the current line doesn't start with ' -- ' then VED will either go
back to the last index line you were on and then move down to the next
one, or else, if you've not yet used <ENTER> g, it will go to the first
index entry.
If the current line starts with ' -- ', i.e. there are TWO spaces
after the hyphens, then it is assumed that instead of section
headers starting with '-- ', they are underlined with hyphens.
The command <ENTER> g invokes the library program VED_G, which does the
work.
VED_G does not care whether the index is at the top, in the middle or at
the end of the file.
-- G_6 Marking a section as read ----------------------------------
If you have already looked at a certain section and don't want <ENTER> g
to find it again, then you can put an extra space, or some other
character at the front of the relevant index entry. It will no longer be
recognised as an index entry, and when looking for the 'next' entry the
program will ignore it. Changing the file in this way will not
permanently alter the file when you quit it if it is a non-writable
library file. If you do it to one of your own writeable files, the file
will be permanently altered.
An alternative to marking a section as read is simply to move the cursor
to the header of a subsequent section then do <ENTER> g. This will move
back to the index, leaving you on the entry for the following section.
-- G_7 Using INDEXIFY to read HELP files with no index ------------
Some HELP and TEACH files have headings in this format, but no table of
contents, as they were written before this facility was added. If you
find it convenient to have a table of contents, the command
<ENTER> indexify
will create one near the beginning of the file. It will not be permanent
if you do not have write-access to the file. You can use it to make
a table of contents for your file. If there is already a table, in the
required format it will be deleted and a new one inserted. It is
therefore unwise to intersperse index entries with comments, as they may
be lost when the table is updated.
If the file uses headings that are underlined with hyphens rather
than the headings in the style shown here, starting with '-- ', then
do
<ENTER> indexify -
-- G_8 Using HEADING to insert headings for VED_G -----------------
If you are creating HELP or TEACH files then you can ensure that the
headings are in the appropriate format for VED_G by typing in a heading,
putting the cursor on line then typing
<ENTER> heading
It first removes any existing leading or trailing hyphens, so can be
used to re-format an old heading too. Thus the heading for the next
section was produced by starting with the line:
G_9 Tailoring VED_G
and typing <ENTER> heading
-- G_9 Tailoring VED_G --------------------------------------------
<ENTER> g invokes the library procedure ved_g.
Users may define procedures which invoke ved_g using a different key
string. The default key string '-- ' is held in the global variable
ved_g_string. The section headers should start with the string followed
immediately by the title of the section. The index entries should start
with a space followed by ved_g_string followed by the title. Both
section headers and index entries may be followed by trailing hyphens
preceded by a space, as above. These will be ignored.
Only the lines in the table of contents should start with the key string
preceded by a space. Only section headers should start with the key
string.
The combination of the key string, and the rest of the line, excluding
any trailing hypens, will be used as a search string to find the
matching item, so it should uniquely identify both the line starting the
relevant section heading and the index entry.
For details see LIB * VED_G
Related procedures LIB * VED_HEADING and LIB *VED_INDEXIFY
POPLOG is a trade mark of the University of Sussex (applied for)
--- C.all//help/enter_g
--- Copyright University of Sussex 1991. All rights reserved. ----------