![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to help.n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / help|
Return to help.n CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / help |
1.1 root 1: .TH HELP 1 "28 May 1984"
2: .SH NAME
3: help \- an easy way to find and use information
4: .SH SYNOPSIS
5: .B help [ \-d
6: dirlist
7: .B ] [ \-m
8: key
9: .B ] [ \-p
10: prompt
11: \fB] [ \-i ] [ \-n ] [ \-q ] [\fP
12: topic
13: .B [
14: subtopic
15: .B [
16: subsubtopic
17: \fB[ ... ] ] ] ]\fP
18: .SH DESCRIPTION
19: The primary purpose of
20: .I help
21: is to provide easy access to on-line documentation.
22: In response to the command
23: .BR help ,
24: the user is placed in an interactive
25: setting and presented with a list of topics and a set of instructions
26: to perform on them.
27: To bypass the interactive part and just display what is known about
28: a topic, enter the topic name on the command line after \fBhelp\fP.
29: .PP
30: A topic is displayed by typing its name or a unique abbreviation,
31: and topics may be requested and listed with numbers.
32: Topics may be saved in a file or printed on the lineprinter.
33: When you request a topic not on its list,
34: .I help
35: can search a set of indexes into its own files,
36: the Unix Programmer's Manual, and various optional off-line sources.
37: References found in this way can be displayed if material is available on-line.
38: All topic requests, including ones which yield no useful information,
39: are automatically recorded for later analysis by system maintainers.
40: Any user may effectively add topics to \fBhelp\fP's knowledge base
41: from that user's point of view by suitably defining the environment
42: variable HELPPOOL.
43: Thus each user can have a private cache of topic files accessible with
44: .IR help .
45: .PP
46: In general the purpose of
47: .I help
48: is to provide a way to move around easily in a set of
49: hierarchical databases, namely, one or more Unix file system subtrees.
50: Although an inherent disadvantage of such databases is that data may be
51: hidden within the hierarchies, the program
52: overcomes this to some extent with its indexing feature.
53: .I Help
54: can be made to serve in special purpose
55: applications without programmer intervention.
56: .PP
57: The following technical description may be of little interest to casual users.
58: .PP
59: The default knowledge base consists of the files and directories in
60: the subtree /usr/lib/help/cat.
61: If the environment variable HELPPOOL contains a list of directories
62: (separated by spaces or colons), their contents are merged with the
63: default list to form the knowledge base.
64: The entire directory pool may be overridden by giving a
65: directory list in
66: .I dirlist
67: after the
68: .B \-d
69: option.
70: .PP
71: The interactive user prompt is by default the tail of argument zero from
72: .IR exec (3),
73: usually ``help'', followed by a list of directories leading
74: to the current subtopic directory.
75: A different prompt may be specified by making a link with a name of your
76: choice to /usr/ucb/help or by specifying a name after the
77: .B \-p
78: option.
79: A special prompt is used in help-index mode,
80: which is entered when the user initiates an index search
81: on a given keyword.
82: The string ``-index'' and the keyword are added to the prompt
83: in this case.
84: .PP
85: .I Help
86: may be invoked with any number of
87: .IR topic ,
88: .IR subtopic ,
89: .IR subsubtopic ,
90: etc., arguments, which may be abbreviated.
91: Starting at the top directory level
92: .I help
93: tries to change to each directory named by successive arguments,
94: interactively resolving non-unique abbreviations along the way.
95: When a name corresponds to a file, the file is displayed and, unless
96: .B \-i
97: was specified, the program exits.
98: If the standard output is not a terminal,
99: .I help
100: refuses to be interactive unless the
101: .B \-i
102: option is given.
103: If the last valid name is a directory, or no topics were requested,
104: .I help
105: lists the topics at the current level and prompts for user input.
106: .PP
107: Maintainers of
108: .IR help -style
109: knowledge bases can use the
110: .B \-m
111: option to perform various custodial functions using shell scripts.
112: Permission to use this option is restricted to those users who
113: have write permission for one of the directories in the list specified
114: after the
115: .B \-d
116: option or in HELPPOOL.
117: If such a directory exists, it (the first one) becomes the value
118: of the variable $subtree, and the local maintenance configuration
119: is sourced from $subtree/../maint/config before most functions are performed.
120: The function name, given as
121: .I key
122: after
123: .B \-m ,
124: may be followed by other arguments (but no topic abbreviations
125: are recognized here), in which case the script
126: $subtree/../maint/do.\fIkey\fP is invoked.
127: In the absence of
128: .IR key ,
129: the word ``default'' is used, usually causing
130: the valid function choices to be listed.
131: .PP
132: A simple macro package called
133: .B \-mayday
134: is used by authors to format
135: .I help
136: topic files.
137: Its purpose is to standardize somewhat the display format for topic files,
138: create a hook for the index generating script, and
139: guarantee page headers and footers of a fixed length so that
140: .I help
141: will not strip out too much or too little of a topic file
142: when displaying it without pagination.
143: The only macro call required is the initializing macro,
144: .BR .TI ,
145: followed by a filename and an optional date on the same line,
146: and by a keyword-rich title (to be useful for the index) on the next line.
147: A handful of other macros are provided for compatibility with other packages,
148: though they are usually unnecessary.
149: .PP
150: Authors of
151: .I help
152: topics may make topic files into shell scripts by entering a # or :
153: at the beginning of the first line.
154: This causes help to run the script when that topic is requested,
155: allowing programs to be demonstrated, questions asked, etc.
156: There are maintenance scripts which will convert a script with embedded
157: .I nroff
158: source text into a script with embedded formatted text, provided
159: the lines to be formatted appear between the special
160: lines ``##nroff'' and ``##''.
161: .PP
162: Similarly, authors may use programs as topic files, the source
163: being written in an aribtrary programming language.
164: .PP
165: The
166: .B \-n
167: option causes topics to be listed and accessible by numbers
168: (and still accessible by unique abbreviations).
169: The
170: .B \-q
171: option suppresses the instruction line appearing before each prompt,
172: including the prompt printed by the
173: .B \-d
174: option to
175: .IR more (1),
176: through which long output is piped after multiple
177: blank lines in a row are reduced to one.
178: Both of these features are available as instructions from within
179: .IR help .
180: .PP
181: The internal instructions are described below.
182: .PP
183: .TP 10
184: \fB% \fRor\fB $\fR
185: Quit from help and return to the shell.
186: Control-d works also.
187: .TP 10
188: topic
189: Display
190: .I topic
191: on the terminal.
192: .I Topic
193: may be the shortest unique name
194: abbreviating a topic at the current level.
195: .I Help
196: prompts for more characters if a non-unique name is given,
197: and asks to look in the index if the name abbreviates no topic.
198: If a name is given as = in any context other than index mode,
199: the current topic is used,
200: where the current topic is defined to be the one most recently accessed.
201: In index mode, a name of = has no special significance, and if
202: .I topic
203: is a unique abbreviation for a reference, that reference
204: is displayed.
205: .TP 10
206: topic\fB +\fP
207: Enter index mode and see what more is known about
208: .I topic
209: by looking in the indexes.
210: A missing topic is taken to be =.
211: .TP 10
212: topic \fB>\fP file
213: Save
214: .I topic
215: in
216: .IR file .
217: A missing topic is taken to be =, and a missing
218: file is taken to be ``helpsave''.
219: If
220: .I file
221: exists the topic file is appended to it.
222: .TP 10
223: topic \fB>&\fP file
224: Save
225: .I topic
226: in
227: .IR file ,
228: preserving headers and footers.
229: Normally, topics are stored as
230: .IR nroff \'d
231: text files, the headers and footers of
232: which are suppressed when displayed on a terminal.
233: They are preserved in
234: .I file
235: with this instruction.
236: .TP 10
237: topic \fB|\fP lpr
238: Print
239: .I topic
240: on the lineprinter, preserving headers and footers.
241: The
242: .I lpr
243: string may be replaced with another program name (such as
244: .I ipr
245: or
246: .IR vpr )
247: followed by one optional argument.
248: A missing
249: .I topic
250: is taken to be the current topic, and a missing
251: .I lpr
252: is taken to be ``lpr''.
253: .TP 10
254: .B ?
255: List the internal instructions and describe them briefly.
256: .TP 10
257: .B .
258: List topics at the current level, indicating the current
259: topic, if any, with an =.
260: In index mode, list references for the current subject.
261: .TP 10
262: .B ..
263: Back up to and list the next higher level of topics.
264: From index mode, this means leave index mode and continue
265: at the previous topic level.
266: .TP 10
267: .B /
268: Back up to and list the top level of topics.
269: From index mode, this means leave index mode and continue
270: at the top level of topics.
271: .TP 10
272: .B <
273: Send comments or other input to the maintainer of
274: .I help
275: via electronic mail.
276: .TP 10
277: .BR ! command
278: Do a Unix
279: .I command
280: and then return to help.
281: All occurrences of = inside
282: .I command
283: will be replaced by the current topic, if any.
284: .TP 10
285: \fB\(**\fP flag \fBon\fP/\fBoff\fP
286: Set
287: .I flag
288: .B on
289: or
290: .B off
291: to adjust the behavior of the program.
292: A missing value for
293: .I flag
294: means invert its current value, and \fB\(**\fP by itself
295: means display the current flags, their settings, and
296: what they signify.
297: There are currently two flags,
298: .B n
299: and
300: .BR q ,
301: which control the same things as the
302: .B \-n
303: and
304: .B \-q
305: options to
306: .IR help .
307: .SH FILES
308: .nf
309: /usr/lib/help/cat root of system \fIhelp\fP files
310: /usr/lib/help/src nroff sources for system \fIhelp\fP files
311: /usr/lib/help/log log of user requests; can be removed
312: /usr/lib/help/maint maintenance scripts
313: /usr/lib/help/cat/general general introduction to \fIhelp\fP
314: /usr/lib/help/cat/index_\(** used to locate further references
315: /usr/lib/tmac/tmac.ayday macro package for \fIhelp\fP files
316: .fi
317: .SH SEE\ ALSO
318: environ(7), exec(3), learn(1), lpr(1), more(1), nroff(1)
319: .SH AUTHOR
320: John Kunze
321: .SH BUGS
322: Pathnames inside topic names are not recognized.
323:
324: .I Help
325: is really just a weak, friendly shell.
326: Strengthening it might be more painful and less useful
327: than civilizing the shell.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.