HELP(1MAN) COMMAND REFERENCE HELP(1MAN) NAME help - interactive manual page browser and general help facility SYNOPSIS help [ -p ] [ [ section ] title ] DESCRIPTION With no title argument, help executes a special set of menus which give general information about using commands in the system. When a title (and possibly a section argument) is given, the command man(1man) is executed in order to get the name of the file containing the formatted manual entry. Because of this, the section argument can be in any of the valid forms for the man command; this manual entry and its index format table (see manindex(5man)) are used to display sections of the manual page. The program has special facilities for maintaining a stack during the session and for ``taking notes'' on a manual entry. Screen Formats Help is a screen-oriented manual page browser with two screen formats. The main screen is divided into three sections: Commands/Information, NAME section, and Current Section. The Commands/Information section has three lines. The left side of first line lists the current manual entry being viewed; the right side of this line lists the top element on the stack followed by the number of items on the stack in brackets ([n]). The left side of the second line is where commands are entered; the right side of this line lists the available section commands for the current manual entry, with the command for the section being viewed in standout mode. The third line of the Commands/Information section is used to print error and information messages. These messages are printed in standout mode. The NAME section of the main screen displays the NAME section from the manual entry. This section lists the names of the items described by the entry and a short description of the items. The Current Section portion of the main screen lists the name of the section, the number of the screen page being viewed, and the total number of screen pages in the section. The other screen format is called the ``alternate screen''. This screen has two sections: Help and Information. Printed 5/12/88 1
HELP(1MAN) COMMAND REFERENCE HELP(1MAN) The alternate screen Help section lists the commands available in that screen on the first two lines, and error messages on the third line. The alternate screen Information section is used to describe the commands in the help system (via the `?' command) and to list the contents of the stack (using the `ps' command). Commands There are five types of commands in the help system: Section commands, Movement commands, Notes commands, Stack commands, and Other commands. Commands may be one or two characters long and are not followed by a return (the system knows when a valid command has been entered). Any character entered that could not be part of a command will cause the terminal bell to be rung. Once the first command character of a two-character command is entered, a backspace will erase that character. Section Commands The section commands cause the different sections of the manual to be displayed. The only valid section commands for a given manual entry are those listed on the right side of the second line of the Command/Information screen section. The following are the available section commands: sy View SYNOPSIS section. de View DESCRIPTION section. op View OPTIONS section. ex View EXAMPLES section. fi View FILES section. va View VARIABLES section. rv View RETURN VALUE section. di View DIAGNOSTICS section. ca View CAVEATS section. se View SEE ALSO section. re View REFERENCES section. no View notes on current entry (see Notes Commands below). Printed 5/12/88 2
HELP(1MAN) COMMAND REFERENCE HELP(1MAN) None of these commands are available in the alternate screen. Movement Commands The movement commands are used to move around in a manual entry section or go to the next or previous section in the entry (the order of the sections is the order listed above in the Section Commands list). Any attempt to move past the start or end of a section causes an error message, except where noted. Movement is limited to pages and half-pages. A page is the number of lines available on the screen to print the current section, and depends on the number of lines on the screen and the number of lines in the NAME section. The following are the available movement commands: <CR> Go to next section in order given above. - Go to previous section in order given above. <sp> Go to next page in current section. If the current page is the last page, go on to the next section in the order given above. ^F Go forward one page. ^B Go back one page. ^D Go forward one half-page. ^U Go back one half-page. 1G Go to first page in section. G Go to last page in section. ^L Redraw screen. The following commands are also available in the alternate screen: <sp>, ^F, ^B, ^D, ^U, and ^L. Notes Commands The help system gives the user the ability to store and view his/her own notes on a given manual entry, such as special examples or known problems. The notes are stored in the directory $HOME/.helpnotes (which is created if need be) under the same name as the manual entry they correspond to. For example, the notes file for the manual entry test(1sh) Printed 5/12/88 3
HELP(1MAN) COMMAND REFERENCE HELP(1MAN) would be stored in the file $HOME/.helpnotes/test.1sh. If there are notes on a manual entry, they can be displayed by using the Section command `no'. Notes can be appended to or edited using the following commands: an Append to notes on current entry. en Edit notes on current entry. The editor to use is determined in the following fashion: If the environment variable HELPEDIT is set, that command is used. If not, the variables EDITOR and EDIT are used, in that order. If none of these are set, vi(1) is used. When either of these commands is invoked, the terminal mode is restored to its original value and the cursor is placed at the bottom of the screen. These commands are not available in the alternate screen. Stack Commands The help system maintains a stack of up to 300 items. Each item in the stack lists the manual entry name, the current section, and the current page in the section; this allows the user to save contexts and return to that context easily. The top element on the stack is listed on the right side of the top line in the Commands/Information section of the main screen. The available stack commands are: pu Push current page/section on stack. po Pop stack. Top element becomes current page/section. sw Swap current page/section for top of stack. This is especially useful for switching back and forth between two manual entries. cs Clear stack. ps Print stack values. The stack items are printed in order from the top of the stack on the alternate screen. The entry name, section, and page are all printed. These commands are not available in the alternate screen. Other Commands There are three commands that do not fall into the above categories. The command `?' prints a description of all of the available commands and error messages in the alternate Printed 5/12/88 4
HELP(1MAN) COMMAND REFERENCE HELP(1MAN) screen. From the main screen, the command `q<CR>' (`q' followed by a carriage return) causes the help system to exit. From the alternate screen, the `q' command returns the user to the main screen. Interrupting the help system at any point will terminate the session. The command `he' is used to look at another manual entry. The command prompts the user for the new entry specification by printing the prompt ``Entry: '' on the second line of the Commands/Information section of the main screen. The entry specification must be less than 67 characters long, be terminated by a return, and be in one of the following formats: <title> (eg, ``test'') <section> <title> (eg, ``1sh test'') <title>(<section>) (eg, ``test(1sh)'') Since many manual entries are simply links to other manual entries (this is done when a manual entry describes more than one item), when the `he' command finds that the new manual entry is the same as the current entry, no change takes place. OPTIONS -p All `he' commands are automatically preceded by an invocation of the `pu' command, thus saving the last section viewed in each manual entry. This is useful for switching back and forth between the current and previous manual entry. EXAMPLES The following example will execute the help system with the manual entry for the command co(1rcs) with all `he' commands interpreted as `pu' and `he'. help -p 1rcs co In addition, if there are no other manual pages for co in section 1, the following command will work the same way. help -p 1+ co FILES $HOME/.helpnotes manual entry notes directory VARIABLES HOME the user's home directory Printed 5/12/88 5
HELP(1MAN) COMMAND REFERENCE HELP(1MAN) HELPEDIT the editor to be used to edit notes EDITOR the editor to be used if HELPEDIT is not set EDIT the editor to be used if HELPEDIT and EDITOR are not set RETURN VALUE [NO_ERRS] Command completed without error. [USAGE] Incorrect command line syntax. Execution terminated. [NP_WARN] An error warranting a warning message occurred. Execution continues. [NP_ERR] An error occurred that was not a system error. Execution terminated. [P_WARN] A system error occurred. Execution continues. See intro(2) for more information on system errors. [NP_WARN] An error warranting a warning message occurred. Execution continues. CAVEATS There is no way to ask for more than one manual entry on the command line. The terminal must have at least 80 columns and 12 lines to use the help command. Standout modes are dependent on terminal types; existing standout modes are underline, bold, and highlight; on color terminals and color workstations a color contrasting with the set display environment is used for standout mode. SEE ALSO apropos(1man), buildif(1man), echo(1sh), makewhatis(1man), man(1man), manintro(1man), section(1man), whatis(1man), man(5man), manindex(5man), whatis(5man), and catman(8man). Printed 5/12/88 6
%%index%% na:312,121; sy:433,213; de:646,2558;3588,2131;6103,2305;8792,2451;11627,1181; op:12808,372; ex:13180,450; fi:13630,154; va:13784,147;14315,221; rv:14536,773; ca:15309,547; se:15856,522; %%index%%000000000219