Return to BSD News archive
Path: sserve!newshost.anu.edu.au!munnari.oz.au!news.Hawaii.Edu!ames!agate!apple!kaleida.com!conklin
From: conklin@kaleida.com (J.T. Conklin)
Newsgroups: comp.os.386bsd.development
Subject: manpage macros (was Some Sample Projects for 386BSD)
Followup-To: comp.os.386bsd.development
Date: 12 Mar 93 12:05:23
Organization: Kaleida Labs, Inc., Mountain View, CA
Lines: 70
Message-ID: <CONKLIN.93Mar12120523@ngai.kaleida.com>
References: <9303090526.AA07265@fubar.cs.montana.edu>
Reply-To: conklin@kaleida.com
NNTP-Posting-Host: ngai.kaleida.com
In-reply-to: nate@fubar.cs.montana.edu's message of 9 Mar 1993 18:13:25 -0800
Nate> Bill gave me a list of projects that he would like to see done, so
Nate> I thought I would share some of them with you.
Nate> 5) Update and clean up man pages. Currently, most of the commands have
Nate> man pages, but there are a few commands that don't. Also, some of
Nate> the man pages need to be updated and cleaned up, since they are
Nate> somewhat old and may require a complete re-write. This is meant as
Nate> no offense to the original man page writers, but things have changed
Nate> and some of the man pages no longer reflect 386BSD. Also, Bill
Nate> mentioned that he would like to see all of the man pages converted
Nate> BACK INTO the old man macros. He mentioned that there are scripts
Nate> out there now that do most of the dirty work, but a person would need
Nate> to verify each man page after it was done, since the scripts aren't
Nate> perfect.
Does anyone else think that converting the man pages to use the old
man macros is an incredibly bad idea?
The new macros provide a simple man-page markup language. Like LaTeX
does with TeX, they separate content from formatting. I think that
this is an very good thing.
For example, if you want to make all optional arguments to commands be
10pt courier oblique bold, you don't have to change all the manpages.
All you need do is to change the macro that controls the format of
optional arguments.
The new macros make it easier to write consistant looking man pages.
Take a look at all of the man pages from net.packages. There have
been hundreds of veriations of how to format function definitions,
command line arguments, etc. Many of the man pages have their own
*roff goop to provide features or shortcuts that the original man
macros didn't provide.
The most significant reason I want to retain the new macros is that
markup languages are significantly easier to parse and transform.
When I was working for Gain Technologies, we wrote a program that
parsed our GEL Programmer's Manual and built an indexed, cross-
referenced, hyper-linked document for use with GainMomentum.
This was possible because the original document was written in LaTeX.
There was no explicit formatting, only tags that indicated that "foo"
was a primitive, or "bar" was a return value. The parser didn't have
to understand all of TeX, only the macros we used.
It would be useful to be able to do the same kinds of things with man
pages. Think of an "xman" program that allowed you to follow cross
references; or displayed different information in different colors and
typefaces.
If we revert to the old man macros, we loose a lot of information. It
would be much more difficult to any of this.
At last month's SVNET meeting Bill stressed the importance of looking
forwards, rather then being mired in the past. I believe that the old
man macros should be left in the past where they belong.
--jtc
--
J.T. Conklin <jtc@wimsey.com> | Your source for floppy distributions
Winning Strategies, Inc. | of the 386BSD OS and binaries
61 Crestwood Drive #18 | Send e-mail for complete product list
Daly City, CA 94015 +---------------------------------------