Re: [Groff] Choosing a portability target

[Clarke Echols]

Eric S. Raymond wrote:
> walter harms <address@hidden>:
 >> It would be a nice step forward to add stuff like pic into man 
pages aka
> > 'a picture says more that 1000 words' (think of flow charts)
>
> In fact, on systems running groff there's no problem with this.
> The constraint has always been that pic won't render well (or, 
> usually, at all) in a terminal emulator, so people don't use it.

In the case of the 1800 or so man pages I was responsible for at HP,
I *never* encountered a need for anything like pic.  I did use eqn
(math pages only) and tbl (because it is an effective way to present
data or structural information in certain situations).  .RS/.RE and
.TP/.IP were very useful for lists.

The key to successful man pages lies in concise, yet very clear
presentation of information and explanations with excellent
examples.  Examples of effective use in somewhat "unusual" situations
(such as how to create a zero-length file) are especially useful,
particularly if properly and thoroughly indexed in a printed manual.

It would be nice to be able to have an index facility online that
goes beyond man -k which uses only the NAME line.  I used embedded
comments in the page to extract index and table-of-contents info for
the printed HP-UX Reference, but they never were visible online.

One of the big defciencies in Windows help is the lack of really
*good* indexing.  But creating good indexes requires a highly
skilled writer who can put himself/herself in the user's frame
of reference and create useful entries and few master that skill.

Clarke