Re: [Groff] Overview, Sept. 2014

[Clarke Echols]

On 09/11/2014 11:57 AM, Ulrich Lauther wrote:
> On Thu, Sep 11, 2014 at 01:11:40PM -0400, James K. Lowden wrote:
> > On Wed, 10 Sep 2014 11:49:37 +0200
> > Ulrich Lauther <address@hidden> wrote:
> >
> > > other modifications would really
> > > improve readability and maintainability:
> > >          - capitalization of class names
> > >          - a naming convention for class member variables
> > >          - reducing the number of global variables
> >
> > You want to tread lightly where style is concerned.  Whether or not
> > something is more "readable" depends very much on what you're used to.
> > There's no consensus in the C ++ community at large on the above
> > recommendations.
> >
> > Many people are accustomed to capitalizing classes and decorating
> > member names.  I think the first is a requirement in Java, and the
> > latter was popularized by Microsoft's ugly "m_varname" convention.   In
> > his books, Stroustrup uses capitalized class names and ordinary,
> > undecorated variable names.
> >
> > Stroustrup has observed that if you ask a room of experts for
> > suggestions on how to improve C++ and make it more accessible to the
> > beginner, you'll be deafened by silence.  If you want a lively
> > discussion, he says, ask where the curly braces should go.
> >
> > >          - for each class a block of comments explaining what the
> > > class is all about
> >
> > For this particular suggestion to appear on the groff list is a little
> > ironic, no? Since the epoch Unix source code has been documented with
> > man pages adjacent to the source in the tree, with its rich formatting
> > features. Surely in-line text-only documentation as comments would be a
> > retrograde step, and a long one at that?  Else we might as well close
> > up shop and rename the project Doxygen!
> 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.
>
> Comments in the source are directed at the programmer, who wants to understand
> HOW the functionality of the program is accomplished.
>
> I think, these are two totally different cups of tea.
>
> I am not a friend of overloading code with comments, like
>          a++; // a is incremented
> but I doubt that a sophisticated mathematical algorithm, e.g., Knuth/Plass's
> dynamic programming approach to paragraph formatting could be understood
> without some helpful comments, including
>          - the task a class is supposed to do or the role these object(s) play
>          - the role of key variables
>          - pseudo code of non-trivial algorithms
>          - pointers to relevant literature
> All this is not to be found in the man-page and does not belong there.
>
>          ulrich

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.

For commands (utilities), syntax, variables, options, and related items
found in a command line are contained in the SYNOPSIS section of the
page.

The DESCRIPTION section identifies the function and use of each of the
recognized elements, with a clear description of each, including any
important considerations when using a particular option or argument.

EXAMPLES are very useful when done well, and require insight into the
needs of the user.

Manpages are not extended nor extensive tutorials.  They assume the
user has basic knowledge of the system and its behaviors, etc.

The system calls and libraries are written for programmers who are
familiar with C and related languages when programming software.

They generally do not get into a description of the internal operations
of a given function or routine.

Also, the manpage should address a single command/utility, function, or
a closely related set of functions when the relationship is obvious.

One example of doing that incorrectly, however, was the AT&T manpage
for cp(1), ln(1), and mv(1).  One of the first things I did when I took
over the HP-UX Reference manual was to write three brand new manpage,
one for each.  That exposed a bunch of holes in the AT&T document.  It
was not nearly as complete as many had supposed.

In AT&T Unix, cp, ln, and mv are handled by a single block of code that
examines the command line argument used when calling it, then modifies
its behavior to conform to cp's, mv's, or ln's expected behavior, as
appropriate.  This is completely invisible to the user, and that's what
made the inadequate single manpage so confusing for users.

In each SYNOPSIS for those three commands, I showed for cp(1), for
example, how to copy a single file, multiple files to a directory,
and multiple files and directories to a directory.  I also showed
how to recursively copy directories and subtrees, each on a single
line.

I then added examples of how to do each in the EXAMPLES section.

That was back in 1989 through 1992 (plus several months in 1985),
and I was told just recently by a former HP employee I didn't even
know that he found that approach very helpful back when he was
using HP-UX in another part of the company.

The key to manpages is simple:  What does the USER really need to
know to do his or her job well?  What does the PROGRAMMER need to
know about a function in order for it to behave correctly in a C
program?

Also important is keeping it useful, easy to access, easy to use,
easy to understand, and helpful for solving the user's problem.

All of this is FWIW.  As a software developer or maintainer, your
interests and needs may vary.

CE