MRMan is a highly configurable online document viewer for the Amiga. It will search for online documentation according to a set of rules and present it to the user with either the standard More text file viewer or a program of the user's choice.
One of the obvious problems with maintaining large amounts of online documentation is the additional disk space required. MRMan helps to alleviate this problem by allowing document files to be compressed with an Amiga version of the Un*x compress program which is available through PD channels. Supplied with MRMan is a special version of compress named zcat. When a compressed document file is encountered, it is first decompressed, using zcat, to a temporary file in the T: directory.
Unlike the Un*x environment, where most online documentation is written for a well-defined structure (nroff man pages in /usr/man... directories), documentation on an Amiga system is likely to have a wide variety of formats, origins and naming conventions. MRMan attempts to accommodate these irregularities with a flexible set of rules for locating documents.
Let's start with MRMan's default behavior. MRMan requires at least two setup steps in order to start functioning. First, copy the files MRMan and zcat to one of the directories defined by your AmigaDOS PATH (e.g. C:, SYS:Utilities, BIN:, etc.). Next, you must assign the logical name MAN: to the device or directory where your online documentation is stored. This is done with the Assign command. Here's an example:
Assign MAN: SYS:Documents
You can also use the -d command line option to force an initial document search point.
MRMan defaults to using the More utility for viewing files. If you wish to override this default, you can set an environment variable, ManViewer , to point to some other suitable text file viewing program (or editor, if you prefer). Just be sure that the program you choose is in the AmigaDOS command PATH. Example:
setenv ManViewer TxView
The location chosen may be a device specification (e.g. df1:) or the name of a directory. If this location contains nested directories, they will also be searched. Oh - just one more thing. It will be beneficial to have some documents online in the location you just chose :-).
When attempting to locate a file corresponding to a particular subject, MRMan "filters out" filenames which do not fit a set of patterns. The simplest pattern is the subject name itself. That is, if a filename is found which exactly matches the subject (case is unimportant), that filename will be chosen. Otherwise, MRMan looks for a filename which consists of the pattern subject.suffix where suffix defaults to one of the following:
man
doc
text
Note that the embedded period is not considered part of the suffix. You can easily patch MRMan to change this set of suffixes. Read the section titled Patching MRMan for more info.
This version of MRMan does not attempt to resolve conflicts when two versions of the same subject appear. The first eligible candidate is always chosen. For instance, if the subject is MRMan and you have document files named MRMan, MRMan.man and MRMan.doc in your MAN: directory, there is a conflict. MRMan will accept any one of these as a valid file. The first eligible file encountered when MRMan scans the ManPath will be selected. Document files which have been compressed will normally have a ".Z" suffix. This suffix is ignored when MRMan applies its eligibility test. For example, MRMan.doc.Z is actually seen as MRMan.doc.
When determining if a file is compressed, MRMan does not rely on the filename extension. Instead, it opens the file and "takes a peek" at the "magic cookie" (1st two bytes) of the document file. Compressed files have a constant value stored at these locations.
While the default lookup rules may be adequate for simple installations, something more is required if you wish to maintain disjoint sets of documentation or if you wish to specify the order in which nested directories are searched. MRMan's extended lookup rules to the rescue! The first extension to these rules is the use of an environment variable. Environment variables were introduced with AmigaDOS 1.3 and exist for the purpose of customizing the behavior of adaptable software. You can define an environment variable named ManPath which will tell MRMan where, and in which order, to search for document files. This concept is very similar to the PATH used by AmigaDOS when it searches for a command file.
For example, I have two major sets of documentation residing on my system. I wish, for housekeeping purposes, to keep these documentation sets in disjoint directories. That is, they do not fall under the same directory hierarchy. The first document set resides under a logical name "Doc:" and the second under a logical name "Docs1.3:". The MAN: document set is comprised of home-brew and PD documentation. The "Docs1.3:" document set contains the Commodore-Amiga "AutoDocs" for AmigaDOS 1.3. When searching for a document, I would like to first search "Doc:", and if the search fails there, proceed to search "Docs1.3:". To establish this search order, I first set the ManPath environment variable:
setenv ManPath "Doc:;Docs1.3:;"
Here is an example of the verbose (-v option) output from MRMan when searching for a document describing the "parallel" device:
MRMan: search path is 'Doc:;Docs1.3:;'. Scanning directory 'Doc:'. Scanning directory 'Doc:ARexx'. Scanning directory 'Doc:Arp'. Scanning directory 'Doc:JS'. Scanning directory 'Doc:System'. Scanning directory 'Doc:Graphics'. Scanning directory 'Doc:WB'. Scanning directory 'Doc:Games'. Scanning directory 'Doc:Misc'. Scanning directory 'Doc:Sound'. Scanning directory 'Doc:Penny'. Scanning directory 'Doc:Unix'. Scanning directory 'Doc:Utilities'. Scanning directory 'Docs1.3:'. Scanning directory 'Docs1.3:Devices'.
Notice that all directories in the "Doc:" directory were scanned. Then, failing the search in "Doc:", MRMan picked up the "Docs1.3:" directory name from the ManPath variable. The document "parallel.doc" was finally located in the directory named "Docs1.3:Devices". For the curious, it took about 4 seconds to locate and present the file. There were 207 files in the "Doc:" hierarchy.
When setting up your ManPath, it is wise to make a few trial runs with the verbose option (-v). Attempt to locate a document that you know doesn't exist. The output will assist you in making refinements in your ManPath. In the example above, two directories, "Doc:JS" and "Doc:Penny" contain files that are not really online documentation. "How do I do dat?", you ask. "Easy", I answer. The device/directory names specified in the ManPath environment variable are considered to be "top-level" directories, which MRMan treats specially (regardless of where they actually reside in your overall filesystem). If a file named "ManPath" (where have you heard that name before?) appears in one of these top-level directories, its contents are expected to contain another search path. The format of this file is the same as for the ManPath environment variable. Directory names are separated by semicolons or newlines. Here's an additional feature. If an element of the ManPath file contains a logical name or device specification (embedded colon), that element will be used as an absolute pathname specification. If the element does not contain a logical name or device specification, it is assumed to be relative to the directory where the ManPath file was found. This may sound a little confusing, so let's look at an example. Remember that our ManPath environment variable is set to "Doc:;Docs1.3:". To eliminate the directories "JS" and "Penny" from the "Doc:" search, I construct a file, named "Doc:ManPath", which looks like this:
Doc:Unix Utilities System Misc ARexx Arp Graphics WB Games Sound
Note that the first line is a full pathname ("Doc:Unix"). This is purely for illustration. The other directory names have an implied prefix of "Doc:" by nature of the fact that they are relative to the directory where the ManPath file was found ("Doc:"). Also interesting to note is that the order of the directory names is different from the original scan. The original scan retrieved ALL directory names in the order that the Amiga filesystem presented them. By using a ManPath file, you can optimize this order to search most frequently accessed directories first.
Taking adaptability to the extreme, MRMan has been designed so that you can easily change the embedded names (MAN:, ManPath, etc.) in the MRMan executable. In order to do this, you must have a binary file editor, such as FileZap. Each item which you can change has a descriptive string preceding it. You'll have to scan the executable to find the "patch area", but it should not be difficult. The patch area is near the end of the file. Search for the string "->" and you'll probably find it on the first try.
Each of the patchable entities has the following format:
# Descriptive text (max length) -> <null> Item text
The Descriptive text will help you identify the nature of the item. The (max length) field defines the maximum number of characters (less terminating null) that you may enter. There MUST be a null byte immediately after the "->" (pointer) and after the Item text.
The items you can change are:
# Temp file name for compressed files (32) -> T:MRManXXXXXX
Compressed files are first decompressed to a temporary file by zcat prior to viewing. Depending upon your configuration, you might want to change this to something like "RAM:MRManXXXXXX". The XXXXXX pattern must exist somewhere in the specification as this is where the unique portion of the filename (multiple MRMan's [MRMen?] may be run simultaneously) is stored.
# Environment device name (32) -> ENV:
Environment variables are treated very similarly to files. If you would rather use some other logical name for the ManPath environment variable (and give up using setenv), it's your choice.
# Search path variable name (32) -> ManPath
If the ManPath environment variable name conflicts with another definition already present in your system, you can choose another name here.
# Man directory logical name (32) -> MAN:
If you already have a preferred logical name for your document hierarchy, you can override MRMan's default here.
# Man search path filename (32) -> ManPath
You are free to name your top-level ManPath file something else.
# Default viewer program name (32) -> More
If you have a text viewer that you prefer over the "standard" More utility, plug its name in here. Just be sure that it's in the AmigaDOS command PATH.
# Suffix 1 (8) -> man
# Suffix 2 (8) -> doc
# Suffix 3 (8) -> text
These are the filename suffixes that MRMan will accept when searching for a document file. Do you need more? Should they be longer? Please let me know!
I'd appreciate feedback on this approach to program adaptability. Many of you probably had your first taste of it when you modified the 1.2 Execute command to reference "T:" rather than ":T". Since this program is released with source, this feature is obviously intended for the non-programmer (who probably doesn't keep a lot of documentation online :-). Was it worth the extra effort?
Mark R. Rinfret 348 Indian Avenue Portsmouth, RI 02871 (401) 846-7639 (home) (401) 849-9390 (work) Usenet: mrr@amanpt1.Newport.RI.US BIX: markr CIS: 72017, 136