Return to help.n CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / help

Annotation of 43BSD/contrib/help/help.n, revision 1.1

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.