[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] Overview, Sept. 2014
From: |
James K. Lowden |
Subject: |
Re: [Groff] Overview, Sept. 2014 |
Date: |
Thu, 11 Sep 2014 17:46:22 -0400 |
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
- Re: [Groff] Overview, Sept. 2014, (continued)
- Re: [Groff] Overview, Sept. 2014, Ingo Schwarze, 2014/09/10
- Re: [Groff] Overview, Sept. 2014, Ulrich Lauther, 2014/09/10
- Re: [Groff] Overview, Sept. 2014, Peter Schaffter, 2014/09/10
- Re: [Groff] Overview, Sept. 2014, Steffen Nurpmeso, 2014/09/11
- Re: [Groff] Overview, Sept. 2014, James K. Lowden, 2014/09/11
- Re: [Groff] Overview, Sept. 2014, Ulrich Lauther, 2014/09/11
- Re: [Groff] Overview, Sept. 2014, Clarke Echols, 2014/09/11
- Re: [Groff] Overview, Sept. 2014,
James K. Lowden <=
- Re: [Groff] Overview, Sept. 2014, Ulrich Lauther, 2014/09/11
- [Groff] Documenting the Source. (Was: Overview, Sept. 2014), Ralph Corderoy, 2014/09/11
- Re: [Groff] Documenting the Source., Werner LEMBERG, 2014/09/12
- Re: [Groff] Overview, Sept. 2014, Ingo Schwarze, 2014/09/14
Re: [Groff] Overview, Sept. 2014, Peter Schaffter, 2014/09/10
Re: [Groff] Overview, Sept. 2014, Bertrand Garrigues, 2014/09/11