RE: [Groff] Re: Groff general issues

[Ted Harding]

On 21-May-99 Werner LEMBERG wrote:
> 
>    > The next step will be then improving --  rudimentary groff
>    > texinfo file does already exist.
> 
>    Would not a man page or two be more appropriate? This is the engine
>    for the man macros, after all.
> 
> Well, it was the choice of the author (Trent A. Fisher
> address@hidden) -- have you ever seen the man pages for perl?  It's
> a horror IMHO!  The whole information is split into more than 30 man
> pages!  A beginner is completely lost.  Because classical man pages
> have no links they are not suited to document a larger amount of data.
> I say `classical' because I've read an announcement of a manpage
> reader (I think on comp.linux.announce) which supports some sort of
> links.

I'm afraid I personally share a distaste for [tex]info! However, I also
agree that man pages are not suitable for conveying large amounts of
detailed information, such as would be required for people learning
how to use the groff package.

My personal preference for groff would be a combination of
a) man pages for usage summaries (options etc), for troff, pic, eqn etc;
b) user manuals for instruction in practical usage.

I have already made a start on a revision of the "Troff User's Manual"
otiginally by Ossanna & Kernighan, to take account of the changes and
extensions in groff. The classical one for pic is quite good, and there
is an even better one (if you've read the other) for gpic by Eric Raymond.

I think there is also a place for man pages for the macro packages too,
but as summaries only. The only proper way to explain the uses of macros
is by mini-manuals. I don't think texinfo ould be particularly good for
this, though I'm willing to be proved wrong.

This said, I have no objection to someone producing texinfo for groff
and family. I think that with a package like groff, the greater the
variety of documentation there is (for different levels of user) the
better.

Whichever way it goes in the end, producing good standalone documentation
for groff & family is going to be a major tasl!

Ted.

--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Date: 21-May-99                                       Time: 20:33:32
------------------------------ XFMail ------------------------------