Convert this to a real man page. Using one blurb of a .Bd -literal

looks rather ugly.

Also slightly adopt the contents to the results of a discussion that
took place in -core some months ago.  We couldn't agree on everything,
but some of the previous sentiments were rather outdated.

1 files changed, 231 insertions, 169 deletions

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index ffd71c4..2e59b79 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -7,14 +7,13 @@
 .Sh DESCRIPTION
 This file contains an example of the preferred style for kernel source
 files in the FreeBSD source tree.
-.in 0
-.Bd -literal
+.Bd -literal -offset 0i
 /*
  * Style guide for the 4BSD KNF (Kernel Normal Form).
  *
  *	@(#)style	1.14 (Berkeley) 4/28/95
  *
- *	FreeBSD $Id: style.9,v 1.3 1995/12/21 18:35:19 phk Exp $
+ *	FreeBSD $Id: style.9,v 1.4 1996/02/09 16:20:10 mpp Exp $
  *
  */
 
@@ -28,62 +27,71 @@ files in the FreeBSD source tree.
  * Multi-line comments look like this.  Make them real sentences.  Fill
  * them so they look like real paragraphs.
  */
-
-/*
- * Kernel include files come first; normally, you'll need <sys/types.h>
- * OR <sys/param.h>, but not both!  <sys/types.h> includes <sys/cdefs.h>,
- * and it's okay to depend on that.
- */
+.Ed
+.Pp
+Kernel include files come first; normally, you'll need <sys/types.h>
+OR <sys/param.h>, but not both!  <sys/types.h> includes <sys/cdefs.h>,
+and it's okay to depend on that.
+.Bd -literal -offset 0i
 #include <sys/types.h>		/* Non-local includes in brackets. */
-
-/* If it's a network program, put the network include files next. */
+.Ed
+.Pp
+If it's a network program, put the network include files next.
+.Bd -literal -offset 0i
 #include <net/if.h>
 #include <net/if_dl.h>
 #include <net/route.h>
 #include <netinet/in.h>
 #include <protocols/rwhod.h>
-
-/*
- * Then there's a blank line, followed by the /usr include files.
- * The /usr include files should be sorted!
- */
+.Ed
+.Pp
+Then there's a blank line, followed by the /usr include files.
+The /usr include files should be sorted!
+.Bd -literal -offset 0i
 #include <stdio.h>
-
-/*
- * Global pathnames are defined in /usr/include/paths.h.  Pathnames local
- * to the program go in pathnames.h in the local directory.
- */
+.Ed
+.Pp
+Global pathnames are defined in /usr/include/paths.h.  Pathnames local
+to the program go in pathnames.h in the local directory.
+.Bd -literal -offset 0i
 #include <paths.h>
-
-/* Then, there's a blank line, and the user include files. */
+.Ed
+.Pp
+Then, there's a blank line, and the user include files.
+.Bd -literal -offset 0i
 #include "pathnames.h"		/* Local includes in double quotes. */
-
-/*
- * Macros are capitalized, parenthesized, and should avoid side-effects.
- * If they are an inline expansion of a function, the function is defined
- * all in lowercase, the macro has the same name all in uppercase. If the
- * macro needs more than a single line, use braces.  Right-justify the
- * backslashes, it makes it easier to read.
- */
+.Ed
+.Pp
+Macros are capitalized, parenthesized, and should avoid side-effects.
+If they are an inline expansion of a function, the function is defined
+all in lowercase, the macro has the same name all in uppercase. If the
+macro needs more than a single line, use braces.  Right-justify the
+backslashes, it makes it easier to read.
+.Bd -literal -offset 0i
 #define	MACRO(x, y) {							\e
 	variable = (x) + (y);						\e
 	(y) += 2;							\e
 }
-
-/* Enum types are capitalized. */
+.Ed
+.Pp
+Enum types are capitalized.
+.Bd -literal -offset 0i
 enum enumtype { ONE, TWO } et;
-
-/*
- * When declaring variables in structures, declare them sorted by use, then
- * by size, and then by alphabetical order.  The first category normally
- * doesn't apply, but there are exceptions.  Each one gets its own line.
- * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;".
- *
- * Major structures should be declared at the top of the file in which they
- * are used, or in separate header files, if they are used in multiple
- * source files.  Use of the structures should be by separate declarations
- * and should be "extern" if they are declared in a header file.
- */
+.Ed
+.Pp
+When declaring variables in structures, declare them sorted by use, then
+by size, and then by alphabetical order.  The first category normally
+doesn't apply, but there are exceptions.  Each one gets its own line.
+Put a tab after the first word, i.e. use
+.Ql int^Ix;
+and
+.Ql struct^Ifoo *x; .
+.Pp
+Major structures should be declared at the top of the file in which they
+are used, or in separate header files, if they are used in multiple
+source files.  Use of the structures should be by separate declarations
+and should be "extern" if they are declared in a header file.
+.Bd -literal -offset 0i
 struct foo {
 	struct	foo *next;	/* List of active foo */
 	struct	mumble amumble;	/* Comment for mumble */
@@ -95,28 +103,35 @@ struct foo *foohead;		/* Head of global foo list */
 typedef struct _bar {
 	int	level;
 } BAR;
+.Ed
+.Pp
+All functions are prototyped somewhere.
+.Pp
+Function prototypes for private functions (i.e. functions not used
+elsewhere) go at the top of the first source module.  Functions
+local to one source module should be declared
+.Ql static .
+.Pp
+Functions used from other parts of the kernel are prototyped in the
+relevant include file.
+.Pp
+Functions that are used locally in more than one module go into a
+separate header file, e.g.
+.Pa extern.h .
+.Pp
+Only use the __P macro from the include file <sys/cdefs.h> if the source
+file in general is (to be) compilable with a K&R Old testament compiler.
+.Pp
+Only the kernel has a name associated with the types, i.e. in the kernel
+use:
+.Bd -literal -offset 0i
+void function __P((int fd));
+.Ed
+.Pp
+in user land use:
+.Bd -literal -offset 0i
+	void function __P((int));
 
-/*
- * All functions are prototyped somewhere.
- *
- * Function prototypes for private functions (i.e. functions not used
- * elsewhere) go at the top of the first source module.
- *
- * Functions used from other parts of the kernel are prototyped in the
- * relevant include file.
- *
- * Only use the __P macro from the include file <sys/cdefs.h> if the source
- * file in general is (to be) compilable with a K&R Old testament compiler.
- *
- * Only the kernel has a name associated with the types, i.e. in the kernel
- * use:
- *
- *	void function __P((int fd));
- *
- * in user land use:
- *
- *	void function __P((int));
- */
 static char	*function __P((int, const char *));
 static void	 usage __P((void));
 
@@ -136,14 +151,15 @@ main(argc, argv)
 	int ch;
 	char *ep;
 
-	/*
-	 * For consistency, getopt should be used to parse options.  Options
-	 * should be sorted in the getopt call and the switch statement, unless
-	 * parts of the switch cascade.  Elements in a switch statement that
-	 * cascade should have a FALLTHROUGH comment.  Numerical arguments
-	 * should be checked for accuracy.  Code that cannot be reached should
-	 * have a NOTREACHED comment.
-	 */
+.Ed
+.Pp
+For consistency, getopt should be used to parse options.  Options
+should be sorted in the getopt call and the switch statement, unless
+parts of the switch cascade.  Elements in a switch statement that
+cascade should have a FALLTHROUGH comment.  Numerical arguments
+should be checked for accuracy.  Code that cannot be reached should
+have a NOTREACHED comment.
+.Bd -literal -offset 0i
 	while ((ch = getopt(argc, argv, "abn")) != EOF)
 		switch (ch) {		/* Indent the switch. */
 		case 'a':		/* Don't indent the case. */
@@ -165,35 +181,39 @@ main(argc, argv)
 	argc -= optind;
 	argv += optind;
 
-	/*
-	 * Space after keywords (while, for, return, switch).  No braces are
-	 * used for control statements with zero or only a single statement.
-	 *
-	 * Forever loops are done with for's, not while's.
-	 */
+.Ed
+.Pp
+Space after keywords (while, for, return, switch).  No braces are
+used for control statements with zero or only a single statement.
+.Pp
+Forever loops are done with for's, not while's.
+.Bd -literal -offset 0i
 	for (p = buf; *p != '\e0'; ++p);
 	for (;;)
 		stmt;
 
-	/*
-	 * Parts of a for loop may be left empty.  Don't put declarations
-	 * inside blocks unless the routine is unusually complicated.
-	 */
+.Ed
+.Pp
+Parts of a for loop may be left empty.  Don't put declarations
+inside blocks unless the routine is unusually complicated.
+.Bd -literal -offset 0i
 	for (; cnt < 15; cnt++) {
 		stmt1;
 		stmt2;
 	}
-
-	/* Second level indents are four spaces. */
+.Ed
+.Pp
+Second level indents are four spaces.
+.Bd -literal -offset 0i
 	while (cnt < 20)
-		z = a + really + long + statment + that + needs + two lines +
-		    gets + indented + four + spaces + on + the + second +
-		    and + subsequent + lines.
-
-	/*
-	 * Closing and opening braces go on the same line as the else.
-	 * Don't add braces that aren't necessary.
-	 */
+		z = a + really + long + statment + that + needs +
+		    two lines + gets + indented + four + spaces +
+		    on + the + second + and + subsequent + lines.
+.Ed
+.Pp
+Closing and opening braces go on the same line as the else.
+Don't add braces that aren't necessary.
+.Bd -literal -offset 0i
 	if (test)
 		stmt;
 	else if (bar) {
@@ -201,91 +221,114 @@ main(argc, argv)
 		stmt;
 	} else
 		stmt;
-
-	/* No spaces after function names. */
+.Ed
+.Pp
+No spaces after function names.
+.Bd -literal -offset 0i
 	if (error = function(a1, a2))
 		exit(error);
-
-	/*
-	 * Unary operators don't require spaces, binary operators do. Don't
-	 * use parenthesis unless they're required for precedence, or the
-	 * statement is really confusing without them.
-	 */
+.Ed
+.Pp
+Unary operators don't require spaces, binary operators do. Don't
+use parenthesis unless they're required for precedence, or the
+statement is really confusing without them.
+.Bd -literal -offset 0i
 	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
 	k = !(l & FLAGS);
-
-	/*
-	 * Exits should be 0 on success, and 1 on failure.  Don't denote
-	 * all the possible exit points, using the integers 1 through 300.
-	 */
-	exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
+.Ed
+.Pp
+Exits should be 0 on success, or according to the predefined
+values in
+.Xr sysexits 3 .
+.Bd -literal -offset 0i
+	exit(EX_OK);	/*
+			 * Avoid obvious comments such as
+			 * "Exit 0 on success."
+			 */
 }
-
-/*
- * If a function type is declared, it should be on a line
- * by itself preceeding the function.
- */
+.Ed
+.Pp
+The function type should be on a line by itself
+preceeding the function.
+.Bd -literal -offset 0i
 static char *
 function(a1, a2, fl, a4)
 	int a1, a2, a4;	/* Declare ints, too, don't default them. */
 	float fl;	/* List in order declared, as much as possible. */
 {
-	/*
-	 * When declaring variables in functions declare them sorted by size,
-	 * then in alphabetical order; multiple ones per line are okay.  Old
-	 * style function declarations can go on the same line.  ANSI style
-	 * function declarations should go in the include file "extern.h".
-	 * If a line overflows reuse the type keyword.
-	 *
-	 * DO NOT initialize variables in the declarations.
-	 */
+.Ed
+.Pp
+When declaring variables in functions declare them sorted by size,
+then in alphabetical order; multiple ones per line are okay.
+Declaring functions inside functions is not recommendable, since their
+linkage scope is always global.  If a line overflows reuse the type
+keyword.
+.Pp
+Be careful to not obfuscate the code by initializing variables in
+the declarations.  Use this feature only thoughtfully.
+.Bd -literal -offset 0i
 	extern u_char one;
 	extern char two;
 	struct foo three, *four;
 	double five;
 	int *six, seven, eight();
-	char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen;
+	char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen;
 	char *overflow __P((void));
 	void *mymalloc __P((u_int));
-
-	/*
-	 * Casts and sizeof's are not followed by a space.  NULL is any
-	 * pointer type, and doesn't need to be cast, so use NULL instead
-	 * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
-	 * against NULL, i.e. use:
-	 *
-	 * 	(p = f()) == NULL
-	 * not:
-	 *	!(p = f())
-	 *
-	 * Don't use '!' for tests unless it's a boolean, e.g. use
-	 * "if (*p == '\e0')", not "if (!*p)".
- 	 *
-	 * Routines returning void * should not have their return values cast
-	 * to any pointer type.
-	 *
-	 * Use err/warn(3), don't roll your own!
-	 */
+.Ed
+.Pp
+Casts and sizeof's are not followed by a space.  NULL is any
+pointer type, and doesn't need to be cast, so use NULL instead
+of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
+against NULL, i.e. use:
+.Bd -literal -offset 0i
+(p = f()) == NULL
+.Ed
+.Pp
+not:
+.Bd -literal -offset 0i
+!(p = f())
+.Ed
+.Pp
+Don't use '!' for tests unless it's a boolean, e.g. use
+.Bd -literal -offset 0i
+if (*p == '\e0')
+.Ed
+.Pp
+not
+.Bd -literal -offset 0i
+if (!*p)
+.Ed
+.Pp
+Routines returning void * should not have their return values cast
+to any pointer type.
+.Pp
+Use
+.Xr err/warn 3 ,
+don't roll your own!
+.Bd -literal -offset 0i
 	if ((four = malloc(sizeof(struct foo))) == NULL)
 		err(1, NULL);
 	if ((six = (int *)overflow()) == NULL)
 		errx(1, "Number overflowed.");
 	return (eight);
 }
-
-/*
- * Don't use ANSI function declarations unless you absolutely have too,
- * i.e. you're declaring functions with variable numbers of arguments.
- *
- * ANSI function return values and braces look like regular functions.
- */
+.Ed
+.Pp
+Don't use ANSI function declarations unless you absolutely have too,
+i.e. you're declaring functions with variable numbers of arguments.
+.Pp
+ANSI function return values and braces look like regular functions.
+.Bd -literal -offset 0i
 int
 function(int a1, int a2)
 {
 	...
 }
-
-/* Variable numbers of arguments should look like this. */
+.Ed
+.Pp
+Variable numbers of arguments should look like this.
+.Bd -literal -offset 0i
 #if __STDC__
 #include <stdarg.h>
 #else
@@ -314,28 +357,47 @@ vaf(fmt, va_alist)
 
 static void
 usage()
-{	/* Insert an empty line if the function has no local variables. */
-
-	/*
-	 * Use printf(3), not fputs/puts/putchar/whatever, it's faster and
-	 * usually cleaner, not to mention avoiding stupid bugs.
-	 *
-	 * Usage statements should look like the manual pages.  Options w/o
-	 * operands come first, in alphabetical order inside a single set of
-	 * braces.  Followed by options with operands, in alphabetical order,
-	 * each in braces.  Followed by required arguments in the order they
-	 * are specified, followed by optional arguments in the order they
-	 * are specified.  A bar ('|') separates either/or options/arguments,
-	 * and multiple options/arguments which are specified together are
-	 * placed in a single set of braces.
-	 *
-	 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
-	 * "usage: f [-a | -b] [-c [-de] [-n number]]\en"
-	 */
+{
+	/* Insert an empty line if the function has no local variables. */
+.Ed
+.Pp
+Use
+.Xr printf 3 ,
+not fputs/puts/putchar/whatever, it's faster and usually cleaner, not
+to mention avoiding stupid bugs.
+.Pp
+Usage statements should look like the manual pages.  Options w/o
+operands come first, in alphabetical order inside a single set of
+braces.  Followed by options with operands, in alphabetical order,
+each in braces.  Followed by required arguments in the order they
+are specified, followed by optional arguments in the order they
+are specified.  A bar
+.Pq Sq \&|
+separates either/or options/arguments,
+and multiple options/arguments which are specified together are
+placed in a single set of braces.
+.Pp
+.Bd -ragged -offset 0.3i
+"usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
+"usage: f [-a | -b] [-c [-de] [-n number]]\en"
+.Ed
+.Bd -literal -offset 0i
 	(void)fprintf(stderr, "usage: f [-ab]\en");
 	exit(1);
 }
 .Ed
+.Pp
+Note that the policy regarding the usage of K&R versus ANSI function
+definitions could not be commonly agreed to.  While keeping the old
+form is more consistent with the existing code base, sticking to it
+defeats the migration to the more modern ANSI style.  For new code,
+chose what you feel is more important.  However, when modifying
+existing subsystems or files, stick with the style that is already
+there.
+.Sh SEE ALSO
+.Xr err 3 ,
+.Xr warn 3 ,
+.Xr sysexits 3
 .Sh HISTORY
 This man page is largely based on the src/admin/style/style file from
 the BSD 4.4-Lite2 release, with a few updates to reflect the current