Search Top Index
HELP VEDGETSYSFILE Mark Rubinstein, August 1985 HELP VEDGETSYSFILEPDR Updated A.Sloman Sept 1990 Browsing With Cross-References In Documentation And Library Files VEDGETSYSFILE, VEDGETSYSFILEPDR and related procedures, VEDNEXTHELP and VEDPREVIOUSHELP provide a mechanism for browsing in documentation files, with automatic access to cross referenced files in different categories, including user-defined documentation categories. CONTENTS - (Use <ENTER> g to access required sections) -- Overview -- Procedures provided -- Formatting for cross references -- Using the facilities -- Mapping 'types' onto search procedures -- Cross references with search strings -- Extending the range of known file types -- For more information see -- Overview ----------------------------------------------------------- POPLOG Provides a browsing facility based on the VED editor. It makes use of: 1. a convention for putting cross references into VED documentation and library files 2. two procedures for finding cross references in the current file 3. a procedure for accessing the files referenced The mechanism assumes that files for online browsing fall into a number of different categories, and that files in different categories are invoked by different procedures. For instance, HELP files are invoked by VED_HELP, TEACH files by VED_TEACH, library files by VED_SHOWLIB, and so on. Files in any category may reference files in any other category, using this mechanism. The accessing procedures are mapped onto keystrokes for convenience. This enables HELP, TEACH, REF, DOC and program library files to be accessed very simply by pointing at an item in the current file with the VED cursor, then pressing a key sequence or function key. When the new file has been read in, further cross references may be accessed in the same way. The files can be abandoned using <ESC> q (or <ENTER> q). The user is not constrained to treat the files in a rigid last-in first-out fashion. Normal VED mechanisms can be used for switching between the different files. (See HELP * VEDFILESELECT and HELP * BUFFERS). The mechanisms may be extended in user programs to provide a browsing facility for user files. -- Overview files ----------------------------------------------------- For each category of system documentation there are overview files, described in HELP * DOCUMENTATION. Working down from these overview files enables the documentation libraries to function partly like a tree-structured menu-driven help system. But since all the accessed files remain in the editor as ordinary VED buffers, the user is not constrained to treat them as in a menu-tree. -- Procedures provided ------------------------------------------------ The following procedures are available to drive the mechanism. VEDNEXTHELP (usually invoked by <ESC> n) finds the NEXT cross-reference in the current file - marked by an asterisk, as in HELP * CONTENTS. VEDPREVIOUSHELP (usually invoked by <ESC> N) finds the PREVIOUS cross- reference in the current file - marked by an asterisk. VEDGETSYSFILE (usually invoked by <ESC> h) reads in the documentation or programm library file so referenced. It uses the property VEDGETSYSFILEPDR which maps words indicating file categories onto access procedures. E.g. The category name "LIB" is mapped onto the procedure VED_SHOWLIB, the category name "HELP" onto VED_HELP. The default category is HELP. -- Formatting for cross references ------------------------------------ The mechanism assumes formatting conventions for cross-references in online files. Each cross reference is of the form <doc-type> * file1 file2 file3 ... The <doc-type> is optional. It is the name of a documentation category e.g. HELP, TEACH, LIB, PLOGHELP, etc), and defaults to HELP if not specified. The asterisk is not essential - it is used only by the VEDNEXTHELP and VEDPREVIOUSHELP facilities described above. The <doc-type> (if present) will only affect files listed on the same line. The file names may optionally be followed by "/" and a search string indicating an item to be found in the file. Examples of cross-references are: HELP * HELPFOR, LIB * HELPFOR Notice that the two files have the same name, but are in different categories. <ESC> h on the first one will get a help file, on the second a program library file, as if the user had typed: <ENTER> showlib helpfor A <doc-type> may be followed by several files: TEACH * TEACHFILES, * GRAMMAR, * PARSING The default <doc-type> is HELP, as the following will show. * LISTS, * DEFINE Examples using search strings: REF * VEDCOMMS/ved_g, HELP * ENTER_G/indexify The effects of these cross-references may be explored by placing the cursor on one of the asterisks (using <ESC> n or <ESC> N) then typing <ESC> h (or invoking the procedure VEDGETSYSFILE). The appropriate documentation or library file is then read in. In REF files, identifier names are denoted by surrounding the name with hyphens, e.g. -foo-. The procedure VEDGETSYSFILE ignores these hyphens, which means you can use <ESC> h to locate the documentation for the identifier. -- Using the facilities ----------------------------------------------- First find the required cross reference in the current file and put the cursor on the asterisk if there is one, or immediately to the left of the file name, e.g. at one of the locations indicated by ^: HELP ENTER_G SHOWLIB HELPFOR TEACH * TEACHFILES ^ ^ ^ Where an asterisk is present it may be located either using ordinary cursor move keys or by means of VEDNEXTHELP (<ESC> n), which searches down the file or VEDPREVIOUSHELP (<ESC> N) which searches up. Then invoke VEDGETSYSFILE (<ESC> h). The appropriate library file will then be found. If there is no type specified then the type is assumed to be HELP. This means that the cursor can be put immediately to the left of ANY word in any file, and <ESC> h typed to see if there is a corresponding help file. E.g. in a program file this can be done with a procedure name to access the relevant help file. -- Mapping 'types' onto search procedures ----------------------------- A file type for searching is indicated by a word which has a value associated with it in the property VEDGETSYSFILEPDR. The value should be either a procedure or the name of a procedure. For example, the procedure might be VED_HELP or VED_TEACH or VED_SHOWLIB or a similar user defined procedure. Before VEDGETSYSFILE runs the procedure, it assigns the file name to VEDARGUMENT. So if invoked with the cursor on the asterisk in HELP * VEDGETSYSFILE it behaves as if the user had given the VED command <ENTER> help vedgetsysfile (If all the characters are the same case, they are mapped onto lower case.) -- Cross references with search strings ------------------------------- If the file name is followed by /<string> then <string> will be searched for when the next file is set on screen. For example use <ESC> n to move your cursor to the asterisks on the lines below and then use <ESC> h to see what files you get. HELP * VALOF, *VEDVARS /vvedgotoplace, *NEWPROPERTY, *VEDPROCS /vedgetsysfile HELP * PROLOG, TEACH * PROLOG, LIB * VED_SHOWLIB -- Extending the range of known file types ---------------------------- Users can associate their own ved searching procedures type names in *VEDGETSYSFILEPDR. For example, try ved_sourcefile -> vedgetsysfilepdr("SOURCE"); SOURCE * vedgetsysfile -- Further reading ---------------------------------------------------- The following should give more information HELP * DOCUMENTATION - General overview of Poplog documentation HELP * DOC - The DOC command HELP * HELP - The HELP command HELP * REF - The REF command HELP * TEACH - The TEACH command HELP * SHOWLIB - The SHOWLIB command HELP * VEDSEARCH - Searching within a file HELP * VEDSYSFILE - Explains how HELP, TEACH, etc work REF * VEDPROCS - Complete list of VED procedures --- C.all/help/vedgetsysfile --- Copyright University of Sussex 1993. All rights reserved. ----------