cstyle.1: modernise

Also remove note about the OS/Net consolidation, now the illumos gate

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125

man/man1/cstyle.1

@@ -20,148 +20,142 @@
 .\"
 .\" CDDL HEADER END
 .\"
-.TH CSTYLE 1 "Aug 24, 2020" OpenZFS
+.Dd May 26, 2021
-.SH NAME
+.Dt CSTYLE 1
-.I cstyle
+.Os
-\- check for some common stylistic errors in C source files
+.
-.SH SYNOPSIS
+.Sh NAME
-\fBcstyle [-chpvCP] [-o constructs] [file...]\fP
+.Nm cstyle
-.LP
+.Nd check for some common stylistic errors in C source files
-.SH DESCRIPTION
+.Sh SYNOPSIS
-.IX "OS-Net build tools" "cstyle" "" "\fBcstyle\fP"
+.Nm
-.LP
+.Op Fl chpvCP
-.I cstyle
+.Op Fl o Ar construct Ns Op , Ns Ar construct Ns …
-inspects C source files (*.c and *.h) for common stylistic errors.  It
+.Op Ar file…
-attempts to check for the cstyle documented in
+.Sh DESCRIPTION
-\fIhttp://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf\fP.
+.Nm
+inspects C source files (*.c and *.h) for common stylistic errors.
+It attempts to check for the cstyle documented in
+.Lk http://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf .
 Note that there is much in that document that
-.I cannot
+.Em cannot
-be checked for; just because your code is \fBcstyle(1)\fP clean does not
+be checked for; just because your code is
-mean that you've followed Sun's C style.  \fICaveat emptor\fP.
+.Nm Ns -clean
-.LP
+does not mean that you've followed Sun's C style.
-.SH OPTIONS
+.Em Caveat emptor .
-.LP
+.
+.Sh OPTIONS
 The following options are supported:
-.TP 4
+.Bl -tag -width "-c"
-.B \-c
+.It Fl c
-Check continuation line indentation inside of functions.  Sun's C style
+Check continuation line indentation inside of functions.
+Sun's C style
 states that all statements must be indented to an appropriate tab stop,
-and any continuation lines after them must be indented \fIexactly\fP four
+and any continuation lines after them must be indented
-spaces from the start line.  This option enables a series of checks
+.Em exactly
-designed to find continuation line problems within functions only.  The
+four spaces from the start line.
-checks have some limitations;  see CONTINUATION CHECKING, below.
+This option enables a series of checks designed to find
-.LP
+continuation line problems within functions only.
-.TP 4
+The checks have some limitations; see
-.B \-h
+.Sy CONTINUATION CHECKING ,
-Performs heuristic checks that are sometimes wrong.  Not generally used.
+below.
-.LP
+.It Fl h
-.TP 4
+Performs heuristic checks that are sometimes wrong.
-.B \-p
+Not generally used.
-Performs some of the more picky checks.  Includes ANSI #else and #endif
+.It Fl p
-rules, and tries to detect spaces after casts.  Used as part of the
+Performs some of the more picky checks.
-putback checks.
+Includes ANSI
-.LP
+.Sy #else
-.TP 4
+and
-.B \-v
+.Sy #endif
+rules, and tries to detect spaces after casts.
+Used as part of the putback checks.
+.It Fl v
 Verbose output; includes the text of the line of error, and, for
-\fB-c\fP, the first statement in the current continuation block.
+.Fl c ,
-.LP
+the first statement in the current continuation block.
-.TP 4
+.It Fl C
-.B \-C
 Ignore errors in header comments (i.e. block comments starting in the
-first column).  Not generally used.
+first column).
-.LP
+Not generally used.
-.TP 4
+.It Fl P
-.B \-P
+Check for use of non-POSIX types.
-Check for use of non-POSIX types.  Historically, types like "u_int" and
+Historically, types like
-"u_long" were used, but they are now deprecated in favor of the POSIX
+.Sy u_int
-types uint_t, ulong_t, etc.  This detects any use of the deprecated
+and
-types.  Used as part of the putback checks.
+.Sy u_long
-.LP
+were used, but they are now deprecated in favor of the POSIX
-.TP 4
+types
-.B \-o \fIconstructs\fP
+.Sy uint_t ,
-Allow a comma-separated list of additional constructs.  Available
+.Sy ulong_t ,
-constructs include:
+etc.
-.LP
+This detects any use of the deprecated types.
-.TP 10
+Used as part of the putback checks.
-.B doxygen
+.It Fl o Ar construct Ns Op , Ns Ar construct Ns …
-Allow doxygen-style block comments (\fB/**\fP and \fB/*!\fP)
+Available constructs include:
-.LP
+.Bl -tag -compact -width "doxygen"
-.TP 10
+.It Sy doxygen
-.B splint
+Allow doxygen-style block comments
-Allow splint-style lint comments (\fB/*@...@*/\fP)
+.Pq Sy /** No and Sy /*!\& .
-.LP
+.It Sy splint
-.SH NOTES
+Allow splint-style lint comments
-.LP
+.Pq Sy /*@...@*/ .
-The cstyle rule for the OS/Net consolidation is that all new files must
+.El
-be \fB-pP\fP clean.  For existing files, the following invocations are
+.El
-run against both the old and new files:
+.
-.LP
+.Sh CONTINUATION CHECKING
-.TP 4
-\fBcstyle file\fB
-.LP
-.TP 4
-\fBcstyle -p file\fB
-.LP
-.TP 4
-\fBcstyle -pP file\fB
-.LP
-If the old file gave no errors for one of the invocations, the new file
-must also give no errors.  This way, files can only become more clean.
-.LP
-.SH CONTINUATION CHECKING
-.LP
 The continuation checker is a reasonably simple state machine that knows
 something about how C is laid out, and can match parenthesis, etc. over
-multiple lines.  It does have some limitations:
+multiple lines.
-.LP
+It does have some limitations:
-.TP 4
+.Bl -enum
-.B 1.
+.It
 Preprocessor macros which cause unmatched parenthesis will confuse the
-checker for that line.  To fix this, you'll need to make sure that each
+checker for that line.
-branch of the #if statement has balanced parenthesis.
+To fix this, you'll need to make sure that each branch of the
-.LP
+.Sy #if
-.TP 4
+statement has balanced parenthesis.
-.B 2.
+.It
-Some \fBcpp\fP macros do not require ;s after them.  Any such macros
+Some
-*must* be ALL_CAPS; any lower case letters will cause bad output.
+.Xr cpp 1
-.LP
+macros do not require \fB;\fPs after them.
+Any such macros
+.Em must
+be ALL_CAPS; any lower case letters will cause bad output.
+.Pp
 The bad output will generally be corrected after the next \fB;\fP,
-\fB{\fP, or \fB}\fP.
+.Sy { ,
-.LP
+or
-Some continuation error messages deserve some additional explanation
+.Sy } .
-.LP
+.El
-.TP 4
+Some continuation error messages deserve some additional explanation:
-.B
+.Bl -tag -width Ds
-multiple statements continued over multiple lines
+.It Sy multiple statements continued over multiple lines
-A multi-line statement which is not broken at statement
+A multi-line statement which is not broken at statement boundaries.
-boundaries.  For example:
+For example:
-.RS 4
+.Bd -literal
-.HP 4
 if (this_is_a_long_variable == another_variable) a =
-.br
+    b + c;
-b + c;
+.Ed
-.LP
+.Pp
-Will trigger this error.  Instead, do:
+Will trigger this error.
-.HP 8
+Instead, do:
+.Bd -literal
 if (this_is_a_long_variable == another_variable)
-.br
+    a = b + c;
-a = b + c;
+.Ed
-.RE
+.It Sy empty if/for/while body not on its own line
-.LP
-.TP 4
-.B
-empty if/for/while body not on its own line
 For visibility, empty bodies for if, for, and while statements should be
-on their own line.  For example:
+on their own line.
-.RS 4
+For example:
-.HP 4
+.Bd -literal
 while (do_something(&x) == 0);
-.LP
+.Ed
-Will trigger this error.  Instead, do:
+.Pp
-.HP 8
+Will trigger this error.
+Instead, do:
+.Bd -literal
 while (do_something(&x) == 0)
-.br
+    ;
-;
+.Ed
-.RE
+.El
-