Re: [Groff] Overview, Sept. 2014

[James K. Lowden]

On Thu, 11 Sep 2014 19:57:43 +0200
Ulrich Lauther <address@hidden> wrote:

> As I understand it, the man-pages are directed at the user of a
> program who wants to know WHAT a program is supposed to do and how
> she can control it via options.

On Thu, 11 Sep 2014 14:48:51 -0600
Clarke Echols <address@hidden> wrote:

> Ulrich is correct.  I was responsible for the HP-UX manpages at HP for
> most of five years.
> 
> Manpages (I always used a combined single word) are for users,
> programmers, and system admistrators.

I think there's some small understanding.  I was referring to

> >>>          - for each class a block of comments explaining what the
> >>> class is all about

I understood that to refer to the reason the class exists and what it
does.  That's insignificantly different from section 3 of the manual;
the user is the programmer, and the purpose is to explain the *what*,
not the how.  

If by "all about" Urich meant a sentence or two, sure, a comment block
is fine.  If by "all about" he meant a description of the semantics of
the public interface (which is what I thought he meant) then ISTM that
belongs in a manual, not in the source code.  N'est-ce pas?

--jkl