patch to style(9) man page to reflect current practices

[Chris Pressey]

On Thu, 5 Feb 2004 12:49:03 +0100
User Joerg <joerg at xxxxxxxxxxxxxxxxx> wrote:

> On Thu, Feb 05, 2004 at 01:34:38AM -0800, Chris Pressey wrote:
> > - Matt doesn't seem to have anything against structname_t, so don't
> > actively discourage it.
> 
> Well, I don't like it. It is the same thing as typedef struct bla;
> There are places in the kernel where you want exactly that, e.g. the
> various bus tags and the like to force the inclusion of the
> corresponding header files, but otherwise it should still be
> discouraged.

Well - isn't that a slightly different thing though?

I agree that typedefs should be, in general, discouraged (I find it a
lot easier to understand 'struct blah **head' than 'blah_t *head')

But if you're going to have typedefs anyway, I don't really care what
the naming convention for them is, as long as there is one.

> > - Note two unspoken rules: what XXX means and how to format keywords
> > that look like functions but aren't (return and sizeof).
> > 
> > - Miscellaneous clarification.  Notably, one long variable name was
> > so long that it caused the example to wrap at 80 columns, which
> > caused the&& operator to appear on the beginning of the next line. 
> > This obscured the point of the example, which is that when lines
> > must be wrapped, operators should appear at the *end* of the line :)
> > 
> > Hoping this might spark some discussion if nothing else.
> 
> Thanks. Keeping style(9) up to date is important. And if only to allow
> better language lawyering ;-)
> 
> I commit your without the above mentioned change. If others feel to
> discuss that further, it can be done later too.

There was one other change I wanted to make, re:

"In header files visible to userland applications, prototypes that are
visible must use either ``protected'' names (ones beginning with an
underscore) or no names with the types.  It is preferable to use pro-
tected names.  E.g., use:
     void    function(int);
     or:
     void    function(int _fd);"

I completely fail to see the rationale for that, but I might be missing
something.  Also, I don't think I've ever seen prototype declarations
like that, but I probably just haven't been looking hard enough.

Anyone have any idea why that clause is in there, and whether it should
be reworded/taken out?  The least that could be done is to clarify why
"protected" names should be used (what do they conflict with?)

-Chris