HELP VED_VMAN (Unix only) Aaron Sloman, Nov 1995 LIB VED_VMAN Makes it easier to find out which Unix "man" files are available and to browse them. It can be used either to build, in VED, an index of man files in a particular category, or to select a file from such an index and read it into VED. The library maps ved_vman onto the VED key sequence "ESC ESC 3" CONTENTS - (Use g to access required sections) -- Background information about the Unix "man" command -- -- "man" categories and subdirectories -- How to use ved_vman -- -- ENTER vman (build an index file) -- -- Bypassing the menu -- -- Selecting a category -- VED key binding changed by LIB VED_VMAN -- More detailed description: two uses of "ENTER vman" -- -- (a) In a vman index file (select a man file) -- -- (b) In some other file -- The structure of a VMAN index file -- vman_default_dirs (Installation specific defaults) -- Selecting a particular man file -- Comparison with xman -- Applicability of ved_vman -- Background information about the Unix "man" command ---------------- The Unix "man" command can be used to search the online "manual" files to obtain information about utilities, system commands, the file system, locally installed program, etc. The VED command "ENTER man", described in HELP * MAN, provides a convenient VED-based interface to the "man" command, when you know the name of the man file that you want. The "man" command searches in one or more directories, which can be determined by the Unix $MANPATH environment variable. This specifies a sequence of directories for the command to search in to find the file whose name you have specified. The environment variable is normally set by your .login file and possibly by other files "sourced" therein. For instance, if your .login file makes available an additional library with its own man files it may extend various search paths, including $MANPATH. As a result, man files that are potentially relevant can be distributed over a collection of directories, making it hard for users to find out about available utilities, even if they are all fully documented. This is not a problem if you know the name of a utility: you can give it as an argument to the unix "man" command or to VED's "ENTER man". But when you don't know the name, the "ENTER vman" enables you to browse the man directories, to find things that may be of interest. In particular it enables you to create a vman index file, listing available man files in a given category (see below). In such an index file the normal VED string search mechanism is available. so you can search for items including (for instance) the substring 'font' in order to discover such utilities as fslsfonts mkfontdir showfont xfontsel xlsfonts fontedit Also you can search for "overview" man files, which usually include the string "intro" as part of their name. -- -- "man" categories and subdirectories There are different categories of man files, e.g. some describing commands that are directly available as shell commands, others describing utilities available only as subroutines for incorporation in user programs (e.g. written in C). All Unix systems have 8 categories, listed below, and some have additional categories, e.g. "local", "new", "old". Not all of these categories are used in all Unix systems. The categories are represented as sub-directories of man directories. E.g. if the main man directory is /usr/man, then sub-directories might be /usr/man/man1 /usr/man/man2 .... /usr/man/man8 and possibly also /usr/man/manl /usr/man/mann /usr/man/mano These subdirectories will contain the "nroff/troff" source files for the manual pages. These files have to be fed through the nroff utility (see MAN nroff) in order to be formatted online. More sophisticated formatting may be available using troff, on some systems. In addition to the sub-directories such as man1 to man8, etc. there may be corresponding "cat" sub-directories cat1 to cat8, etc. containing already pre-processed versions of the man files (which have been through nroff). In addition either the man files or the cat files may be compressed or not. Directories containing compressed man files may have the suffix ".Z", e.g. /usr/man/man1.Z (e.g. on HP-UX). Thus there are many different cases, and ved_vman may not cope perfectly with all of them. -- How to use ved_vman The ved_vman procedure gives you the option to select a category to browse in, or to specify that you want ALL categories. -- -- ENTER vman (build an index file) To try it out, type ENTER vman That will autoload ved_vman, and run the procedure to give you a menu of "man" types, corresponding to volumes 1 to 8 "local", "new" or "old" or all. (Not all of these categories of man files exist on all systems.) The menu is in two parts, as the whole thing is too long to display on the status line. So you'll first be shown the menu *:all 1:commands 2:system calls 3:routines 4:devices ?:others If you type the character "?" it will show the remaining options: 5:files 6:games 7:misc 8:admin l:local n:new o:old ?:others If you type the character "?" again it will switch back to the first menu. If for any reason the screen gets corrupted before you choose your option (e.g. because of broadcast messages) you can type CTRL-L to have the options re-displayed and the screen refreshed. -- -- Bypassing the menu If you know in advance which category you want, you can type the relevant character directly as argument to the vman command, e.g. ENTER vman 3 Get section 3 of the man files ENTER vman * Get all sections ENTER vman 1c Get section 1c, under Solaris The next section tells you more about the categories. -- -- Selecting a category Note that the labels describing the categories are approximate, and may be quite inaccurate in some Unix systems: you have to gain experience of your own system. Most user commands are found in category 1 and category l (local). To select a category, type its number, or the letter starting its name, or, if you wish to look at ALL categories, type an asterisk "*" If you have made a selection for which no man files exist, it will tell you. When you have chosen, ved_vman gets a list of all the man files in that category, in all the man libraries in your man search path. The list of file names is read into a temporary VED file, described below as a "vman index file". When the VED cursor is in a vman index file you can choose to look at one of the files listed, simply by putting the cursor over or to the left of its name, and giving the "ENTER vman" command, or pressing REDO if the "vman" command is still on the command line. (See HELP VEDNEWKEYS/REDOCOMMAND, or HELP VEDKEYS/REDOCOMMAND) -- VED key binding changed by LIB VED_VMAN ---------------------------- When the library is loaded it defines a procedure ved_vman_init which when run alters VED's key-binding so that the sequence ESC ESC 1 is mapped onto a call of ved_vman. It does this by a defining a procedure ved_vman_init that is invoked at the beginning of ved_vman. This sets up the key-binding and then redefines itself to do nothing. The default value is define ved_vman_init(); vedset keys "ENTER vman" = esc esc 1 endvedset identfn -> ved_vman_init enddefine; this may be re-defined by users. To suppress the above, do this before loading ved_vman (e.g. in your vedinit.) global vars ved_vman_init = identfn; -- More detailed description: two uses of "ENTER vman" ---------------- The command "ENTER vman" has two forms of behaviour, -- -- (a) In a vman index file (select a man file) ENTER vman In an index of man files previously created by "ENTER vman", the command fetches the man file that the VED cursor is on or to the left of. -- -- (b) In some other file ENTER vman If not invoked in a vman-produced index of man files, gets you an index of available man files in a category. It first prompts you on the status line to specify which category, by selecting from one of the menus described above. When you have selected the category of man files, it then traverses directories in your $MANPATH to find all those man files that are in the given category, and lists them in a VED buffer, grouped by directory. Note: Some directories may be duplicated because of the structure of $MANPATH -- The structure of a VMAN index file --------------------------------- The first line of an index file will contain the string 'VMAN INDEX: MAN FILES FOUND (put cursor on one then REDO)' This should not be changed, as it is used by ved_vman to recognise vman index files. Next will come a "CONTENTS" list in the format produced by ved_indexify (see HELP * VED_INDEXIFY), giving the names of directories in which man files in the selected category were found. The index may look like this: CONTENTS - (Use g to access required sections) -- /bham/X11/man/man1: -- /bham/X11/pd/man/man1: -- /bham/man/man1: -- /bham/ums/X11/man/man1: -- /bham/ums/man/man1: -- /usr/man/man1: It is possible to use the standard VED "ENTER g" command to go to a particular directory in order to browse the files located there. In some cases some empty directories will also be listed as such. This is because of the search patterns used. Basically the file is created by a command using Unix "ls", except that an index is added. -- vman_default_dirs (Installation specific defaults) ----------------- If you have not set the environment variable $MANPATH then then ved_vman uses the list of directory names held in the variable vman_default_dirs, which defaults to ['/usr/man' '/usr/local/man'] This default can be changed to suit local sites, by altering the declaration in LIB * VED_VMAN. -- Selecting a particular man file ------------------------------------ If the VED cursor is in a vman index file, then in order to select a particular man file you can move the VED cursor to the desired name and pres REDO to read it, or do ENTER vman or do ESC ESC 1 This invokes the ved_man command to read in the man file. -- Comparison with xman ----------------------------------------------- A partly similar browsing facility is provided by the "xman" program distributed as part of the MIT X Window utilities library, except that xman requires you to do visual searching in the window of options, whereas ved_vman gives a VED window listing the options, making it easy to use VED's string search mechanism, as described above. Also ved_vman shows you which directory each man file is in, helping you to understand how the different libraries you use are structured. Moreover, you can save the index files produced by ved_vman and use them again later, instead of rebuilding every time, which can be slow with xman. Also, because ved_vman creates a VED file, you can, of course, keep several man files and index files and your own files in VED and flip between them very quickly. Finally you don't need to be running X to use ved_vman, neither does the machine that you run it on need to have authority to create a new X window on your terminal (unless you use it with XVed, of course). -- Applicability of ved_vman ------------------------------------------ The present version has been tested only on SunOS and on HP-UX running on an HP 68040 server. These two use different methods of storing man files (e.g. they are mostly compressed on HP-UX). When a selected file is viewed ved_vman uses ved_man, which, in turn, uses the local version of "man", which should therefore be able to cope with the local format. --- $poplocal/local/help/ved_vman --- The University of Birmingham 1995. --------------------------------