cvs commit: src/share/man/man9 style.9

[Bruce Evans]

On Wed, 5 Jan 2005, Warner Losh wrote:

[Warner Losh didn't write]
> > I thought the reason for the - is that it prevented indent(1) from trying to
> > reindent that comment block and thus there might be comment blocks with a
> > leading '/*-' that aren't copyrights.
>
> There might be, yes, and I've added a note to style(9) in my tree
> explaining that.  In a quick straw poll of the source tree, I found no
> comments starting in column 1 that weren't a license statement.

Comments starting in column 1 and also in line 1?  Indent protection is used for much more than copyrights, so /*- doesn't give a hint that the
comment might be a copyright except near line 1.

> That's true that's what the /*- is for, but if any come to light, you
> can change it to /** just as easily.

"/**" also means indent protection.

Gnu indent's man page claims to also treat comments beginning with
"/*=" and "/*_", and even normal block comments, as being box comments
and thus automatically protected from indent.  Apart from a better
default, gnu indent's handling of block comments seems to be worse
than FreeBSD's.  gnu indentntly always treats block comments as box
comments and thus doesn't reformat them, while FreeBSD defaults to
reformatting them but has -fcb and -nfcb options to control their
formatting.  I added these options because reformatting of block
comments is usually not wanted but is sometimes useful.

BTW, in at least FreeBSD indent, there are other strange magic characters
after "/*".  A block comment is defined as a comment with a newline
immediately after the "/*-".  Whitespace between the "/*" and the
newline breaks the blockness of a comment.  This causes some
intended-as-block comments with trailing whitespace after "/*" to be
reformatted despite -nfcb.

Bruce