ManDoc.tioga
Copyright Ó 1991 by Xerox Corporation. All rights reserved.
Ch. Le Cocq, July 26, 1988
Christian Le Cocq July 29, 1988 5:20:38 pm PDT
Michael Plass, October 3, 1991 11:07 am PDT
Jim Thornton July 20, 1993 4:08 pm PDT
Man
CEDAR 10.0
Man: Unix man pages in Cedar
a (sort of) troff to tioga translator
Christian Le Cocq
© Copyright 1988, 1991, 1993 Xerox Corporation. All rights reserved.
Abstract: Man allows the Cedar user to access the Unix(tm) man pages as tioga documents. The resulting tioga files are cached locally.
Created by: Christian Le Cocq
Maintained by: friendly users
Keywords: man, troff, unix, tioga
XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304
Man News
July 20, 1993
Made a number of changes to improve behavior when multiple pages match the given name.
(1) Introduced search modes (all, first, section, list)
(2) Introduced user profile fields to control search process
(3) Modified handling of "too many matches" case, so the first n are presented, and the value of n can be set on a per-user basis
(4) Removed all reference to remoteHostName, which wasn't supported anyway
(5) Enhanced documentation
June 16, 1993
Changed title displayed in viewer and icon to the manual page name and section number. This change only affects the man command.
Changed reporting of unsupported troff operators so only one line is used for the report.
July 2, 1992
Fixed handling of .so and .nx requests. Now relative paths (eg. man3/gettext.3) are interpreted as references into the man directory tree in which the requesting page is stored, rather than as relative paths in the working directory of the commander.
1. Introduction
The Man package provides access to the rich (well at least complex) structure of the Unix(tm) manual pages which is washed out on a tty-type window. Man pages are converted to Tioga documents, permitting the use of scrolling, Tioga levels, etc.
Usage
man Tioga access to the Unix(tm) man pages.
Usage: man [-f | -a | -l | sectionNumber] name
The first argument (optional) specifies the mode. The switches are:
-f First page: lowest section number, earliest directory in $MANPATH
-a All pages
-l List of pages: produces a list of the commands to access each specific page
Alternatively, a sectionNumber may be specified to access the page from that section.
The second argument is the name of the desired page.
LocalMan file
Tioga access to a (local) man page
LocalMan can be used to convert a man-page file to Tioga, even though it may not conform to the man directory conventions, or may be masked by another page with the same name.
2. Man Command - Manual Page Lookup
The
Man command performs a function analogous to the Unix(tm) man command: it searches a series of directories organized according to standard conventions to locate a page with a given name. When the page is located, it is usually formatted as a Tioga document and opened. The series of directories to be used is taken from the Commander property
MANPATH, the format of which is described below. It is possible that there are multiple pages with a given name, in which case the course of action to be followed is dictated by the
Search Rule in force.
Search Rules
There are four mutually exclusive search rules (modes actually) which may be used:
(1) All [switch -a, profile token: All]
In this mode, pages with the given name are opened, up to a user-definable limit. For historical reasons, this is the default rule.
(2) First [switch -f, profile token: First]
In this mode, only one page is opened, and that is the page having the lowest section number. In case of multiple pages with the lowest section number, the one that is opened is the one which occurs in the directory tree that appears first in the MANPATH.
(3) Section [switch is the section number itself, not settable from user profile]
When a section number (word beginning with a digit) is specified as the first argument of the command, all pages in that section, and subsections, with the given name will be opened, up to the user-definable limit. Note that specifying 3 as the section will open pages in sections 3v, 3w, etc.
(4) List [switch -l, user profile token: List]
The List rule causes pages to be reported rather than opened. For each page, one line is emitted into the Commander typescript. The line is a command which will cause the page to be opened if executed. The purpose of this mode is to permit a user to see all the possibilities for a particular page name. To open any one of them, it is only necessary to copy the line into the Commander.
3. LocalMan Command - Formatting from a file
The LocalMan command provides a way to format a manual page as a Tioga document, given the file name of the nroff source for the page. The command formats and opens the manual page contained in the specified file. This command may be useful in cases when the file is available but is not stored according to the conventions in a directory structure referenced by MANPATH. This command may also be useful for accessing a particular page, when that page would not be selected by the First search rule.
4. Defaults - User Profile and MANPATH
MANPATH
The MANPATH Commander property specifies the series of directory trees which will be searched by the Man command, as does the Unix(tm) environment variable of the same name. The property value should be a colon (:) separated list of directories, each of which is the root of a manual page directory tree. The Cedar Man package only looks at the mann subdirectories, where n is a digit indicating the section number.
User Profile Settings
Operation of the Man command may be controlled by the following entries in the user profile:
Man.SearchRule: Specifies the default search rule. The value must be a token, one of:
All All rule (same as not including the user profile entry)
First First rule
List List rule
The default search rule may be overridden on any command by use of arguments.
Man.MaxMatches: The maximum number of matches. The value must be a positive integer. Searching for matches will terminate after the specified number have been found.
5. Caching
To avoid the necessity of formatting a page for Tioga every time it is required, formatted pages are cached in the /tmp directory of the local workstation. The cache file names consist of the complete path of the source file from which the man page was obtained, with /'s replaced by #'s, and .tioga appended.
Caching is a simple formatting optimization only, and does not affect searching at all. There is no automatic mechanism to ensure that cache copies are up to date, so the system works best for pages which are stable.
6. Limitations and Bugs
The man-page parsing is based on the macros most commonly used in man pages, not the full troff semantics. Some valid troff operators will be reported as undefined. Some of the formatting may not be correct, and some content may be included even when it is not supposed to appear.
Unrecognized nroff operators are reported to the user. If pages include other pages, there may be a series of such reports.
The distinction between alternative choices in the output produced according to the List rule is not always clear.
One could argue that it should be possible to combine List mode and Section mode.
There is no support for the functionality of Unix(tm) "man -k" or "appropos".
Cache consistency is not checked.