more fixups to style(9)

[Chris Pressey <cpressey@xxxxxxxxxxxxxxx>]

Hi all,

Some fixups to style(9):

Rewording: style(9) is a goal rather than an absolute requirement or an
observation, so replace some occurances of "must be" and "is" with
the clearer "should be".

Clarify usage of /* FALLTHROUGH */.

Eat our own dogfood in example code w.r.t. no space after return.

Use .Dx for DragonFly and .Fx for FreeBSD.  (Unfortunately, .Dx doesn't
seem to expand properly for me for some reason.  I thought that change
was in the tree already, but maybe not?)

Be explicit about: that the register keyword should not be used, and
that there should be no space before commas.

Change rule for wrapping long parameter lists in function declarations
from "use 4 spaces" to "make it line up", and adjust sample code to
match.

Other minor typological fixups.

-Chris

Index: style.9
===================================================================
RCS file: /home/dcvs/src/share/man/man9/style.9,v
retrieving revision 1.6
diff -u -r1.6 style.9
--- style.9	25 Feb 2004 17:35:29 -0000	1.6
+++ style.9	26 Feb 2004 11:07:39 -0000
@@ -31,7 +31,7 @@
 .Nd "kernel source file style guide"
 .Sh DESCRIPTION
 This file specifies the preferred style for kernel source files in the
-.Fx
+.Dx
 source tree.
 It is also a guide for preferred userland code style.
 Many of the style rules are implicit in the examples.
@@ -243,7 +243,7 @@
 typedef	const long	baz;		/* This is baz. */
 .Ed
 .Pp
-All functions are prototyped somewhere.
+All functions should be prototyped somewhere.
 .Pp
 Function prototypes for private functions (i.e. functions not used
 elsewhere) go at the top of the first source module.
@@ -251,7 +251,7 @@
 local to one source module should be declared
 .Ic static .
 .Pp
-Functions used from other parts of the kernel are prototyped in the
+Functions used from other parts of the kernel should be prototyped in the
 relevant include file.
 .Pp
 Functions that are used locally in more than one module go into a
@@ -259,11 +259,14 @@
 .Qq Pa extern.h .
 .Pp
 Avoid using the
+.Ic register
+keyword and the
 .Dv __P
 macro from the include file
 .Aq Pa sys/cdefs.h .
-Code in the DragonFly source tree is not
-expected to be K&R compliant.
+Code in the
+.Dx
+source tree is not expected to be K&R compliant.
 .Pp
 Changes to existing files should be consistent with that file's conventions.
 In general, code can be considered
@@ -292,7 +295,7 @@
 to line up:
 .Bd -literal
 static char	*function(int _arg, const char *_arg2, struct foo *_arg3,
-		    struct bar *_arg4);
+			  struct bar *_arg4);
 static void	 usage(void);
 
 /*
@@ -325,7 +328,9 @@
 .Ic switch
 statement that cascade should have a
 .Li FALLTHROUGH
-comment.
+comment, unless they contain no code of their own, as in the
+.Ic case '?'
+element in the example below.
 Numerical arguments should be checked for accuracy.
 Code that cannot be reached should have a
 .Li NOTREACHED
@@ -372,7 +377,7 @@
 		stmt;
 	for (;;) {
 		z = a + really + long + statement + that + needs +
-		    two lines + gets + indented + four + spaces +
+		    two + lines + gets + indented + four + spaces +
 		    on + the + second + and + subsequent + lines;
 	}
 	for (;;) {
@@ -403,7 +408,7 @@
 	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 +
+		    two + lines + gets + indented + four + spaces +
 		    on + the + second + and + subsequent + lines;
 .Ed
 .Pp
@@ -426,18 +431,18 @@
 		stmt;
 .Ed
 .Pp
-No spaces after function names.
-Commas have a space after them.
-No spaces
+Do not put spaces after function names,
 after
 .Ql \&(
 or
 .Ql \&[
-or preceding
-.Ql \&]
-or
+characters, or preceding
+.Ql \&] ,
 .Ql \&)
+or
+.Ql \&,
 characters.
+Do put spaces after commas.
 .Bd -literal
 	error = function(a1, a2);
 	if (error != 0)
@@ -567,7 +572,7 @@
 		err(1, (char *)NULL);
 	if ((six = (int *)overflow()) == NULL)
 		errx(1, "number overflowed");
-	return (eight);
+	return(eight);
 }
 .Ed
 .Pp
@@ -582,7 +587,8 @@
 .Ed
 .Pp
 Use ANSI function declarations instead.
-Long parameter lists are wrapped with a normal four space indent.
+Long parameter lists are wrapped so that the first parameter on each line
+lines up with the first parameter on the previous line.
 .Pp
 Variable numbers of arguments should look like this.
 .Bd -literal
@@ -676,7 +682,7 @@
 .Fx
 KNF
 .Nm
-compliant in the repository must not diverge from compliance.
+compliant in the repository should not diverge from compliance.
 .Pp
 Whenever possible, code should be run through a code checker
 (e.g.,