home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Fred Fish Collection 1.5
/
ffcollection-1-5-1992-11.iso
/
ff_disks
/
200-299
/
ff281.lzh
/
MRMan
/
mrman.man
< prev
next >
Wrap
Text File
|
1989-11-20
|
16KB
|
397 lines
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
1mNAME
0mMRMan - online manual reader
1mSYNOPSIS
MRMan0m[-1md 0m<1mdirectory0m>] [-1mv 0m(1mverbose0m)] <1msubject0m>[...<1msubject0m>]
1mDESCRIPTION
0mMRMan 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 1mMore 0mtext 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 1mcompress 0mprogram which is available through PD
channels. Supplied with MRMan is a special version of
1mcompress 0mnamed 1mzcat0m. When a compressed document file is
encountered, it is first decompressed, using 1mzcat0m, to a
temporary file in the 1mT0m: directory.
1mDefault Document Lookup Rules
0mUnlike 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 1mMRMan 0mand 1mzcat 0mto one of the
directories defined by your AmigaDOS PATH (e.g. C:,
SYS:Utilities, BIN:, etc.). Next, you must assign the
logical name 1mMAN0m: to the device or directory where your
online documentation is stored. This is done with the
1mAssign 0mcommand. Here's an example:
Assign MAN: SYS:Documents
You can also use the -1md 0mcommand line option to force an
initial document search point.
MRMan defaults to using the 1mMore 0mutility for viewing files.
If you wish to override this default, you can set an
environment variable, 1mManViewer 0m, 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:
MRSoft -1-
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
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 3msubject.suffix 0mwhere
3msuffix 0mdefaults 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 1mPatching MRMan 0mfor 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 3mMRMan 0mand you have document files named 1mMRMan0m,
1mMRMan0m.1mman 0mand 1mMRMan0m.1mdoc 0min your 1mMAN0m: 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, 1mMRMan0m.1mdoc0m.1mZ 0mis actually seen as 1mMRMan0m.1mdoc0m.
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.
1mExtended Document Lookup Rules
0mWhile 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 1mManPath 0mwhich will tell MRMan
where, and in which order, to search for document files.
MRSoft -2-
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
This concept is very similar to the 1mPATH 0mused 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
MRSoft -3-
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
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 3mimplied 0mprefix 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.
1mPatching MRMan
0mTaking 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
MRSoft -4-
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
The 3mDescriptive text 0mwill help you identify the nature of
the item. The 3m(max length) 0mfield 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 3mItem text.
0mThe items you can change are:
# Temp file name for compressed files (32) -> T:MRManXXXXXX
Compressed files are first decompressed to a temporary file
by 1mzcat 0mprior 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
MRSoft -5-
MRMAN(1) AM*GA Programmer's Manual MRMAN(1)
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?
1mAUTHOR
0mMark 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
MRSoft -6-
