[[ I don't know if moving this to tech-userlevel at this point is
"right", or not... ]]

[ On Tuesday, July 18, 2000 at 20:09:49 (+0100), David Brownlee wrote: ]
> Subject: Re: bin/7249
>
> 	I like manpages, but I agree there are a couple of obvious
> 	features missing compared to some other formats:
> 
> 	    -  Follow references to other documents
> 	    -  Jump to, or even see an index of sections
> 	    -  Sanely search for implemented commands or similar
> 	       (eg: Just try to lookup the 'complete' syntax in tcsh(1))

The first issue is easily fixed by using "info" as your documentation
browser.  It properly follows "xrefs" in existing manual pages.

The second issue is not quite fixed by "info", though that's just a
small matter of creating a suitable index in the appropriate format.

The third issue is another matter completely.  No matter what "format"
complex documentation is written in, it needs to be written in such a
way that concise reference information concerning the topic is available
in easily accessible form_s_.  Good, useful, technical documentation is
hard to write, especially for complex topics.  One potential "fix" for
this issue within the current framework would be to create new separate
"chapters" for complex tools, such as interpreters, so that logical
breakdowns of their documentation would be accessible with existing
tools (eg. something like "man 1sh syntax" would display a manual page
containing a concise description of the syntax, and only the syntax, for
"sh").  Once upon a time the manual page for "rn" was the canonical
example of a "bad" manual page, and this fame was soon taken over by
"perl"....

> 	Switching the man page source format to html would address some of
> 	those issues, at a tradeoff many people are not willing to make.

Ah, um, as has already been asked, what's wrong with "nroff -mdoc2html"?

(other than, of course, the obvious limitations, including its existing
TODO list, in the current implementation?  Eg. it should be relatively
quick work to have ".Xr" translate into a special-purpose ".Lk" and thus
also provide a way of satisfying the first issue above.)

-- 
							Greg A. Woods

+1 416 218-0098      VE3TCP      <gwoods@acm.org>      <robohack!woods>
Planix, Inc. <woods@planix.com>; Secrets of the Weird <woods@weird.com>