HELP VED_INDEXIFY A.Sloman Dec 1988
Updated A.Sloman June 1991
ENTER indexify
ENTER heading
ENTER g
or
ENTER indexify <string>
ENTER heading <string>
ENTER g <string>
Facilities for building headings and tables of contents and accessing
desired sections of a VED file. The <string> argument defaults to the
value of ved_g_string
CONTENTS - (Use ENTER g to access required sections)
-- Overview
-- ENTER indexify (build or re-build table of contents)
-- ENTER g (Go to table of contents, or to section indicated)
-- ENTER heading (Format current line as a heading)
-- Using ved_g_string to alter header format
-- Using a key string argument to temporarily alter ved_g_string
-- Creating an index of indexes
-- Creating different families of VED index procedures
-- See also:-- Overview -----------------------------------------------------------
This collection of routines makes it easy to insert and use a table of
contents in a VED file.
For a tutorial introduction to these facilities see HELP * ENTER_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, but can be varied as indicated below. If the default is
used, then all index entries start with ' -- ' and all section header
lines start with '-- '.
In general, the section headers should start with the string in
ved_g_string followed immediately by the title of the section, as in
this file.
The index entries should start with a space followed by ved_g_string
followed by the title, as in the table of contents above.
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, otherwise the ENTER indexify command will include those lines
in the table of contents.
The ENTER g command, used with the cursor on a line in the table of
contents, or index, uses the combination of the the key string and the
rest of the line, excluding any trailing hypens, as a search string to
find the matching section header line. So it is important that index
entries should uniquely identify the relevant section heading and the
index entry.
-- ENTER indexify (build or re-build table of contents) -------------
Creates a table of contents summarising the headings in the
file. It can be used with ENTER g to go to a desired heading.
Two formats for headings are supported, though they cannot be mixed
in the same file.
One format is the kind of heading shown in this file, with two hyphens
on the left and a row of trailing hyphens. The other format is
underlined headings, such as can be found in the REF files. (E.g. see
REF * SYSTEM/access)
The ENTER indexify command determines which type of heading is in use
and builds a table of contents appropriately. There is a slight
difference in the format of the table of contents, which enables the
ENTER g command to determine what kind of heading to search for.
If there is not yet a table of contents, the indexify command will build
one where the cursor is. It need not be at the beginning of the file.
If an old table of contents exists the indexify command will delete it
and insert a new one in the same place. However, if additional text had
been inserted in the old table that portion of the table will not be
deleted, and a warning message to that effect is displayed. It is then
up to the user to delete the remaining portion of the old index and
re-insert the extra text in the new table if required.
-- ENTER g (Go to table of contents, or to section indicated) -------
If the cursor is not on the table of contents, this command will move
it there. On the first occasion of use it will go to the first entry in
the table. Thereafter it goes to the entry after the previous one
accessed.
If the cursor is on a line in the table of contents inserted by
ved_indexify then the ENTER g command will move the cursor to the
beginning of the section indicated by that line of the table of
contents.
The ENTER g command does not assume that the table of contents is near
the beginning or near the end of the file. It can be inserted anywhere
in the text. In fact, the table can be broken down into sub-tables that
are located in different places in the file, though in that case it is
not easy to re-build the distributed table of contents automatically.
-- ENTER heading (Format current line as a heading) -----------------
This command is used to produce section headers in the format shown in
this file. For example if the cursor is placed on the following line
ANOTHER HEADING
and the command ENTER heading is given, then that line will be
formatted as a heading. Thereafter ENTER indexify will re-build the
table of contents so as to include this line, and the ENTER g command
can be used to access it.
-- Using ved_g_string to alter header format --------------------------
The standard versions of the commands described above assume that
headings start with two hyphens and a single space, at the left of the
line. The heading may end with a row of hyphens. The table of contents
then uses the same initial string indented by an extra space, and
deletes any trailing hyphens after the heading.
Users may change the format by assigning a new string to the global
variable ved_g_string, whose default value is the string '-- '. E.g.
to use three plus signs (without a space) to indicate a section heading
do
'+++' -> ved_g_string;
The new string will then be used by the commands
ENTER heading
ENTER indexify
ENTER g
However, at present no mechanism is provided to tell VED to use
different values of ved_g_string for different files, though users could
easily define procedures that use a property to store such an
association (See REF* PROPS), then within each procedure re-define
ved_g_string locally (see HELP * DLOCAL) and call the above procedures.
WARNING: 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.
-- Using a key string argument to temporarily alter ved_g_string ------
All these commands can be given a different local value for ved_g_string
by giving the string (minus the trailing space) as an argument. E.g. if
you wish to have an index in a file of Pop-11 procedure definitions you
can build the index using
ENTER indexify define
(This will, however, ignore procedure headings that are indented, e.g
nested procedure definitions.) Try the above after doing
ENTER showlib elizaprog
Having built the index you can go to it with
ENTER g define
which, if repeated, will take you to the procedure definition
corresponding to the cursor location in the index.
Similarly, if you wish to have headings flagged by "===" then you
can create them using
ENTER heading ===
As in
=== Sample heading 1 --------------------------------------------------
=== Sample heading 2 --------------------------------------------------
And you can build an index using
ENTER indexify ===
As in
CONTENTS (===)
=== Sample heading 1
=== Sample heading 2
And then, to go to a location in the index you use
ENTER g ===
As this example shows, two sorts of headings, with diferent indexes, can
be used in the same file. E.g. in a tutorial file you could have a
collection of normal section headings with a normal index, and a
separate index to the examples.
-- Creating an index of indexes ---------------------------------------
Note that if you give an argument to ved_indexify it puts the argument
in parentheses after 'CONTENTS', to identify different section headings.
you can then have an index of indexes, if you do
ENTER indexify CONTENTS
Which, in this file, produces
CONTENTS (CONTENTS)
CONTENTS (===)
CONTENTS (CONTENTS)
Note that it does not include the "main" table of contents, like the one
at the top of this file, unless after producing it you remove leading
spaces in the 'CONTENTS' line.
-- Creating different families of VED index procedures ----------------
Procedures that permanently use different values for ved_g_string
are easily constructed by partially applying veddo to the appropriate
command strings, e.g.
global vars procedure
ved_newheading = veddo(% 'heading ===' %),
ved_newindexify = veddo(% 'indexify ===' %),
ved_newg = veddo(% 'g ===' %);
-- See also:
HELP * ENTER_G
LIB * VED_G
LIB * VED_HEADING
LIB * VED_INDEXIFY
--- C.all/help/ved_indexify
--- Copyright University of Sussex 1988. All rights reserved. ----------