>   Modified files:
>     share/man/man9       style.9
>   Log:
>   Clarify style(9) WRT comments following #endif, #else.

I noticed a lot more problems with this.  Notes on my patch:

% Index: style.9
% ===================================================================
% RCS file: /home/ncvs/src/share/man/man9/style.9,v
% retrieving revision 1.94
% diff -u -2 -r1.94 style.9
% --- style.9	28 Oct 2002 19:33:22 -0000	1.94
% +++ style.9	29 Oct 2002 08:39:55 -0000
% @@ -83,5 +123,5 @@
%  #ifndef lint
%  static char sccsid[] = "@(#)style	1.14 (Berkeley) 4/28/95";
% -#endif /* !lint */
% +#endif /* not lint */
%  #endif
%

This is supposed to give an example of a vendor id, not an example of a
comment on an #endif.

% @@ -181,5 +224,5 @@
%  .Ed
%  .Pp
% -When code blocks are conditionally defined using
% +When code is conditionally compiled using
%  .Ic #ifdef
%  or

I think "blocks" is just confusing here.  It can be confused with C blocks,
but the blocks that we're talking about here only become blocks when we
add #ifdefs to delimit them.  Elsewhere, the term "region" is mostly used
for these blocks.  I tried to use that term more consistently.

Code isn't defined.  s/defined/compiled/ here and elsewhere gave large
changes.

% ...
% @@ -195,17 +238,17 @@
%  .Ic #ifdef 's
%  may be confusing to the reader.
% -Exceptions may be made for cases where code is contionally undefined for
% -the purposes of lint, even though the undefined region may be small.
% -The comment shall be seperated from the
% +Exceptions may be made for cases where code is conditionally not compiled for

Code isn't undefined either.

Spelling fix: s/contionally/conditionally/.

% +the purposes of lint, even though the uncompiled region may be small.
% +The comment should be separated from the

"seperated" shall be separated from written English, but separation of
the comment is not so imperative.

% ..
% -should match the expression used in
% +should match the expression used in the corresponding
%  .Ic #if
%  or

Wording improvement (?).

% @@ -213,8 +256,11 @@
%  The comment for
%  .Ic #else
% -should be the inverse of the expression used in the previous
% +and
% +.Ic #elif
% +should match the inverse of the expression(s) used in the preceding
%  .Ic #if
% -or
% -.Ic #elsif .
% +and/or
% +.Ic #elsif
% +statements.
%  In the comments, the subexpression
%  .Dq Li defined(FOO)

Attempt to describe comments on #elif's better.  A simple inverse is
not right, especially if there are multiple #elif's.  I didn't want
to be so precise as to formally describe that the inverse is of all
the preceding expressions logically or'ed together, but perhaps this
can be summarized better.

Wording improvement (?): s/previous/preceding/.

Spelling/syntax fix: s/#elsif/#elif/.

% @@ -231,5 +277,5 @@
%
%  #ifdef COMPAT_43
% -/* A long block here, or other conditional code. */
% +/* A large region here, or other conditional code. */
%  #else /* !COMPAT_43 */
%  /* Or here. */
% @@ -237,5 +283,5 @@
%
%  #ifndef COMPAT_43
% -/* Yet another long block here, or other conditional code. */
% +/* Yet another large region here, or other conditional code. */
%  #else /* COMPAT_43 */
%  /* Or here. */

Try to use "region" consistently.

Unannotated patch:

%%%
Index: style.9
===================================================================
RCS file: /home/ncvs/src/share/man/man9/style.9,v
retrieving revision 1.94
diff -u -2 -r1.94 style.9
--- style.9	28 Oct 2002 19:33:22 -0000	1.94
+++ style.9	29 Oct 2002 08:39:55 -0000
@@ -83,5 +123,5 @@
 #ifndef lint
 static char sccsid[] = "@(#)style	1.14 (Berkeley) 4/28/95";
-#endif /* !lint */
+#endif /* not lint */
 #endif

@@ -181,5 +224,5 @@
 .Ed
 .Pp
-When code blocks are conditionally defined using
+When code is conditionally compiled using
 .Ic #ifdef
 or
@@ -189,5 +232,5 @@
 or
 .Ic #else
-to permit the reader to easily discern where conditionally defined code
+to permit the reader to easily discern where conditionally compiled code
 regions end.
 This comment should be used only for (subjectively) long regions, regions
@@ -195,17 +238,17 @@
 .Ic #ifdef 's
 may be confusing to the reader.
-Exceptions may be made for cases where code is contionally undefined for
-the purposes of lint, even though the undefined region may be small.
-The comment shall be seperated from the
+Exceptions may be made for cases where code is conditionally not compiled for
+the purposes of lint, even though the uncompiled region may be small.
+The comment should be separated from the
 .Ic #endif
 or
 .Ic #else
 by a single space.
-For short conditionally defined regions, a closing comment should not be
+For short conditionally compiled regions, a closing comment should not be
 used.
 .Pp
 The comment for
 .Ic #endif
-should match the expression used in
+should match the expression used in the corresponding
 .Ic #if
 or
@@ -213,8 +256,11 @@
 The comment for
 .Ic #else
-should be the inverse of the expression used in the previous
+and
+.Ic #elif
+should match the inverse of the expression(s) used in the preceding
 .Ic #if
-or
-.Ic #elsif .
+and/or
+.Ic #elsif
+statements.
 In the comments, the subexpression
 .Dq Li defined(FOO)
@@ -231,5 +277,5 @@

 #ifdef COMPAT_43
-/* A long block here, or other conditional code. */
+/* A large region here, or other conditional code. */
 #else /* !COMPAT_43 */
 /* Or here. */
@@ -237,5 +283,5 @@

 #ifndef COMPAT_43
-/* Yet another long block here, or other conditional code. */
+/* Yet another large region here, or other conditional code. */
 #else /* COMPAT_43 */
 /* Or here. */
%%%

Bruce

