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

[Chris Pressey]

This started out as a simple replacement of 'FreeBSD' with 'DragonFly'
and got out of hand, to the point where it's probably politically
sensitive :)  To summarize:

- we're actively moving away from K&R, so actively discourage old-style
declarations.

- Matt doesn't seem to have anything against structname_t, so don't
actively discourage it.

- 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.

-Chris
Index: style.9
===================================================================
RCS file: /home/dcvs/src/share/man/man9/style.9,v
retrieving revision 1.4
diff -u -r1.4 style.9
--- style.9	27 Jan 2004 21:03:08 -0000	1.4
+++ style.9	5 Feb 2004 00:49:33 -0000
@@ -40,11 +40,11 @@
 is silent on an issue.
 .Bd -literal
 /*
- * Style guide for FreeBSD.  Based on the CSRG's KNF (Kernel Normal Form).
+ * Style guide for DragonFly.  Based on the CSRG's KNF (Kernel Normal Form).
  *
  *	@(#)style	1.14 (Berkeley) 4/28/95
  * $FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $
- * $DragonFly: src/share/man/man9/style.9,v 1.4 2004/01/27 21:03:08 dillon Exp $
+ * $DragonFly$
  */
 
 /*
@@ -57,6 +57,12 @@
  * Multi-line comments look like this.  Make them real sentences.  Fill
  * them so they look like real paragraphs.
  */
+
+/*
+ * XXX in a comment indicates code which is incomplete, suboptimal,
+ * or otherwise deserving of further attention.
+ */
+
 .Ed
 .Pp
 Version control system ID tags should only exist once in a file
@@ -225,9 +231,6 @@
 When convention requires a
 .Ic typedef ,
 make its name match the struct tag.
-Avoid typedefs ending in
-.Dq Li _t ,
-except as specified in Standard C or by \*[Px].
 .Bd -literal
 /* Make the structure name match the typedef. */
 typedef struct bar {
@@ -252,18 +255,15 @@
 separate header file, e.g.\&
 .Qq Pa extern.h .
 .Pp
-Only use the
+Avoid using the
 .Dv __P
 macro from the include file
-.Aq Pa sys/cdefs.h
-if the source
-file in general is (to be) compilable with a K&R Old Testament compiler.
-Use of the
-.Dv __P
-macro in new code is discouraged, although modifications
-to existing files should be consistent with that file's conventions.
+.Aq Pa sys/cdefs.h .
+Code in the DragonFly source tree is not
+expected to be K&R compliant.
 .Pp
-In general code can be considered
+Changes to existing files should be consistent with that file's conventions.
+In general, code can be considered
 .Dq "new code"
 when it makes up about 50% or more of the file(s) involved.
 This is enough
@@ -400,12 +400,12 @@
 	}
 .Ed
 .Pp
-Indentation is an 8 character tab.
-Second level indents are four spaces.
+Indentation used for program block structure is an 8 character tab.
+Second level indents used for line continuation are four spaces.
 If you have to wrap a long statement, put the operator at the end of the
 line.
 .Bd -literal
-	while (cnt < 20 && this_variable_name_is_too_long_for_its_own_good &&
+	while (cnt < 20 && this_variable_name_is_really_far_too_long &&
 	    ep != NULL)
 		z = a + really + long + statement + that + needs +
 		    two lines + gets + indented + four + spaces +
@@ -452,8 +452,8 @@
 Unary operators do not require spaces, binary operators do.
 Do not use parentheses unless they are required for precedence or unless the
 statement is confusing without them.
-Remember that other people may
-confuse easier than you.
+Remember that other people may become
+confused more easily than you.
 Do YOU understand the following?
 .Bd -literal
 	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
@@ -502,13 +502,19 @@
 Hiding file declarations in what appears to be a local
 scope is undesirable and will elicit complaints from a good compiler.
 .Pp
-Casts and
-.Ic sizeof Ns 's
-are not followed by a space.
+Casts are not followed by a space.
 Note that
 .Xr indent 1
 does not understand this rule.
 .Pp
+For the purposes of formatting, treat
+.Ic return
+and
+.Ic sizeof
+as functions.  In other words, they are not
+followed by a space, and their single argument
+should be enclosed in parentheses.
+.Pp
 .Dv NULL
 is the preferred null pointer constant.
 Use
@@ -570,7 +576,7 @@
 }
 .Ed
 .Pp
-Old-style function declarations look like this:
+Avoid old-style function declarations that look like this:
 .Bd -literal
 static char *
 function(a1, a2, fl, a4)
@@ -580,7 +586,7 @@
 {
 .Ed
 .Pp
-Use ANSI function declarations unless you explicitly need K&R compatibility.
+Use ANSI function declarations instead.
 Long parameter lists are wrapped with a normal four space indent.
 .Pp
 Variable numbers of arguments should look like this.