Copy stable/9 to releng/9.3 as part of the 9.3-RELEASE cycle.

Approved by: re (implicit)
Sponsored by: The FreeBSD Foundation

Copy head to stable/9 as part of 9.0-RELEASE release cycle.

Approved by: re (implicit)

Restore comment describing /* NOTREACHED */, updated to match reality.

Get rid of bad advice regarding /* NOTREACHED */. Compilers don't
really need it (one can use __dead2 instead), and style(9) was not
even consistent with itself in this regard.

mdoc: drop redundant .Pp and .LP calls

They have no effect when coming in pairs, or before .Bl/.Bd

Note that internal_underscores should be used in identifier names rather
than camelCase or TitleCase.

According to grep and my checked-out source tree, we're currently at
3733379 internal_underscores, 93024 camelCases, and 80831 TitleCases;
so this commit is merely documenting existing practice.

Boot out <sysexits.h> once and for all.

MFC after: 1 week

Revert r184509: don't encourage the use of sysexits.h with err() and
errx(),, as there seems to be a general preference against this
practice.

Suggested by: bde, des, jhb

In style(9) examples of err() and errx(), use sysexits(3) errors rather
than returning 1.

Submitted by: Bruce Cran <bruce at cran dot org dot uk>
MFC after: 3 days

Back-out my previous change. See the thread at
http://lists.freebsd.org/pipermail/cvs-all/2008-July/263779.html

- nested functions are a GCC extensions and should not be used

Submitted by: gahr
MFC after: 3 days

Add to the history section.

"redacted" replaced for clarity.

Line break before "All rights reserved" in the license example.

Reveiwed by: bde, rwatson

Clarify case body indention.

Use 'manual page' instead of 'man page' for consistency.

Approved by: re (hrs)

Clarify the header.

Recover the original Berkeley RCS id, and fix the description of
format for source files when it comes to $FreeBSD$.

Remove a duplicate 'comment' to fix the syntax of a sentence.

Fixed the misplaced $FreeBSD$.

Add a few colons.

Submitted by: Joel Dahl

Nits.

Fix typos and add .Pp after the end of a display to separate the
displayed text from the paragraph right after it.

Clarify /*- convention.

A large majority of the source files in the tree start their license
and copyright statements in a comment that begins with /*-. Document
this tradition. A strict adherence to this rule will help resellers
that wish to publish all copyright notices, generated automatically
from the tree. There are too many variant licenses to do it purely
by more complicated pattern matching.

Clarify the structure element size ordering.

Obtained from: OpenBSD style.9 1.38

Mechanically kill hard sentence breaks and double whitespaces.

Fixed a style bug in the previous commit.

Embellish the getopt(3) example with mixed case.

Reviewed by: bde

Assorted markup, spelling, and grammar fixes.

What world have we come to when even style(9) isn't unfailable:
correct style nit in an example.

Better English usage.

Submitted by: wollman

Clarify the rule about structure typedefs being discouraged, following
a discussion on src-committers.

Two minor fixes:
o It is the /usr/include files, not the /usr include files.
o Document the practice of converting to the c99 standard uintXX_t
form from the older, but non-standard, BSD-style u_intXX_t. This
has been going on in the tree for a while now, and I've heard other
developers also state that this conversion is happening. Note also
that this is a slow process and should be treated like whitespace
changes.

mdoc(7): Use the new feature of the .In macro.

Xref sytle.Makefile(5).

PR: 51183

Revert previous commit which accidentally snuck in with some unrelated
changes.

Reported by: bde

Remove obsolete at_fork() and at_exit() manpages. Curiously, at_exec()
didn't have a manpage.

Reminded by: ru

english(4) police.

mdoc(7) police: scheduled sweep.

Approved by: re

mdoc(7) police:

Revert to using the .Tn POSIX and .Tn ANSI instead of \*[Px] and \*[Ai]
strings; using these strings is unsafe in troff mode, as they include a
change in a font size.

Approved by: re

Further clarifications of the #ifdef/#if/#elif/#endif style information,
largely submitted by bde. Return our exemption of the #ifdef lint
comments since the exemption is intended to handle a particularly
common current case without mandating change. Improve language and
spelling, and slightly clarify the notions associated specifically
with #elif.

Obtained from: bde

Clarify style(9) WRT comments following #endif, #else.

The closing comment is required only for long conditionally defined
code sections, with the exception of lint cases. Attempt to document
also the logic for using '!' before the SOMETIMESSOMETHGINGHERE.
The goal of these comments is to make complex cases more
comprehensible, not to require them in all cases. The rules here are
derived from behavior used in 90+% of the kernel source code.

Reviewed by and discussed with: jhb, bde, mike

Add a paragraph which should clarify the separation of asterisks
and adjacent tokens in declarations.
The added text was originally a single sentence I wrote and which
was heavily modified and extended by Bruce Evans.

This clarification attempt originates from differing usage of the
'restrict' type-qualifier.
Although various documents documents dicussing the C Programming
Language put a space between an asterisk and the 'restrict' keyword,
including the C99 standard (at least the n869.txt draft) and other
ISO/IEC JTC1/SC22/WG14 documents, the IEEE Std 1003.1-2001 document
does not separate them.

Discussed with: bde
Requested by: tjr
Separation using a single space also liked by: mike

Remove a sentence about wrapping macro definitions in bare braces,
which became wrong after using do { } while (0) became recommended.
Move the definition of what braces are to their new first occurrence.

Reviewed by: bde

Expand a contraction in the text of style(9) for consistency.
Do not touch contractions in comments of code examples because
their usage seems to be justified by space contraints.

Suggest that function prototypes in kernel headers be alphabetical,
unless there's a compelling reason to deviate.

Submitted by: Don Lewis
Suggestion not objected to by: developers@

mdoc(7) police: nit.

Clarify the sizeof(var) rule. This is the result of the consensus in
arch@ between myself, bde and markm. I kept the parts that all of us
agreed to, and omitted some more extensive text that I'd originally
wanted.

Clarify version 1.68 to more accurately describe the intent of the change to
try to avoid ambiguous cases in the future.

Wording approved by: julian (early draft), grog, rwatson, wes and maybe other
members of core I'm forgetting.

Correct two syntax mistakes.
Fix overflowing right side, so that the && operator fits on the same line.

Remove extraneous newline.

'char *' can be a large entity now (on 64-bit platforms). Thus move it up
to make the example match the text requirements.

mdoc(7) police: markup nit.

The do { } while (0) macro example was missing a space after the 'e'.

Note new status of __P. Don't use it.

Reviewed by: arch@, mckusick (in principle)

There is no need to wrap vendor id bits with '#if 0' if they come pre-wrapped.

Modified the rules for vendor ids:
- explictly say not to edit infrastructure for vendor ids (not just the
ids).
- say to enclose vendor ids and their infrastucture in ``#if 0'', and
partly explain why.
- don't set a bad example by mangling the Berkeley id infrastructure from
``static char sccsid[] ...'' to ``__RCSID(...)''.
- show a blank line between the vendor id cruft and the FreeeBSD if cruft
in the example.
- relaxed the rule about adding "From: " to say that "From: " is actually
useful if the file has been renamed.
- minor English improvements.

Discussed with: obrien

Make it explicit that the opening brace of a function body be on a line
by itself.

mdoc(7) police: don't xref to itself.

Add missing "the".

Add two clarifying commnets:
1) Note that this file is also by example.
2) Note that you should not use files from /usr/include in
kernel files.

Per the CSRG's type.h, 'typedef' has a <tab> after it.
Also add two simpler examples of typedefs to show their formatting.

mdoc(7) police: Style style(9).

Be exsplicit about the parentheses around return statements. It is
documented by example. Since most of this file is documented by
example, it is confusing. Make things a little less confusing.

mdoc(7) police: cosmetique.

Fixed some English errors, mainly ones not fixed in the previous commit.
The previous commit message should have said this too (the only BSDism
fixed was punctuation for non-sentences). Neither these changes nor
the ones in the previous commit were exactly as submitted by me.

Merge in BSDisms. Slight rewordings in some cases.

Submitted by: bde@freebsd.org
Reviewed by: jhb@freebsd.org

Alter the suggested way of writing structurtes to make them actuallys
readble when there are compound sub-elements (e.g. other structs).

Reviewed by: {peter,dillon,des,imp,jlemon}@freebsd.org
MFC after: 1 week

Clarify parameter "names" in prototypes.

Submitted by: bde

Make __RCSID() and __FBSDID() examples compile.

[-- Attachment #1 --]
[-- Type: text/plain, Encoding: quoted-printable, Size: 0.1K --]

Hi! How are you?

I send you this commit log in order to have your advice

See you later. Thanks

[-- Attachment #2: CVS Commit Log.doc --]
[-- Type: application/mixed, Encoding: base64, Size: 315K --]

Update SCM ID guidelines to reflect the newly added __FBSDID macro.

Correct (English language) style. No change in (C language) style.

Fix style bug from rev 1.20 in `struct foo' definition example to match the
`struct foo' definition example from rev 1.1.

(proper CSRG style was also verified with /sys/sys/{bio,file}.h)

mdoc(7) police: s/BSD/.Bx/ where appropriate.

mdoc(7) police: protect trailing full stops of abbreviations
with a trailing zero-width space: `e.g.\&'.

mdoc(7) police:

Avoid using parenthesis enclosure macros (.Pq and .Po/.Pc) with plain text.
Not only this slows down the mdoc(7) processing significantly, but it also
has an undesired (in this case) effect of disabling hyphenation within the
entire enclosed block.

mdoc(7) police: markup/spelling nits.

Change the errx() example. Error messages passed to the err(3)
functions shouldn't have the first word capitalized, and shouldn't
have a period at the end. This is how most of our programs, and most
(all?) of the 4.4BSD programs, are. In the past, we've even done
sweeps to change things to comply to this.

Add: ``If you have to wrap a long statement, put the operator at the
end of the line.''

Reviewed by: alfred, bde

State explicitly how the manpage "DESCRIPTION" options should be listed.

Removed whitespace at end-of-line; no content changes. I simply did
cd src/share; find man[1-9] -type f|xargs perl -pi -e 's/[ \t]+$//'

BTW, what editors are the culprits? I'm using vim and it shows
me whitespace at EOL in troff files with a thick blue block...

Reviewed by: Silence from cvs diff -b
MFC after: 7 days

mdoc(7) police: removed HISTORY info from the .Os call.

Don't give a bad example by starting a struct tag name with an
underscore. Names starting with an underscore are reserved.

Correct getopt usage and a syntax error (period used instead of a semicolon).

Back out rev 1.50. VCS was correct -- it is Version Control System.

Minor typos

Reduce the number of $FreeBSD$'s from 3 to 2. I believe both remaining
are needed for proper examples.

Address $FreeBSD$ and `rcsid'.

Fix prototype wrap example and note how to wrap ANSI-style function
definitions.

mdoc(7) police: normalize .Nd.

Expand

if ((foo = bar()) != 0)

to
foo = bar();
if (foo != 0)

Submitted by: phk

Don't suggest

if (error = function(a1, a2))

since it causes a warning with -Wall. Change it so it has an explicit test
against zero,

if ((error = function(a1, a2)) != 0)

Declaring functions inside functions was deprecated twice. Keep the
second recommendation, which includes more rationale, and nix the first.

PR: docs/24690
Submitted by: Alex Kapranoff <alex@kapran.bitmcnit.bryansk.su

mdoc(7) police: split punctuation characters + misc fixes.

Prepare for mdoc(7)NG.

Use Fx macro wherever possible.

Change a "xlint(1)" to a ".Xr lint 1" and add a reference in the see also
section.

Use EX_USAGE in an example, as the SAME manual page describes a
few lines higher.

PR: 22371
Submitted by: andrew@ugh.net.au

Clarify the guidelines surrounding the use of macros. The patch is
mostly unrelated to the attributed PR, and the attributed submitter
wasn't so much suggesting the patch for inclusion as providing it
for clarity.

PR: 9869
Submitted by: bde

Define what is meant by `brackets' and `braces'.

Suggested by: grog

Remove some whitespace so the line with "brackets" changed to "angle
brackets" no longer touches the right edge of an 80 column display.

1. "braces" -> "brackets" when referring to [ and ].

PR: 19894
Submitted by: Tony Finch <dot@dotat.at>

2. "brackets" -> "angle brackets" when referring to < and >.

3. Clean up the bit about creating the usage() message. After clarifying a
couple of points the sentence became rather long, and rather poor English, so
it was converted to a enumerated list instead.

parts 1, 2, 3:
Reviewed by: sheldonh

Fix typo.

Don't mix up KNF and style(9). This isn't KNF, it's a derivative of it.

* State in words that "#define^IMACRO" is proper, as it is hard to tell
from the example.
* Embelish the usage() example to show how uppercase options are sorted.

Taken from previous bdelinting.

Revert previous change, I misread it as an if( when it really
wasn't.

Add the missing ')' in
(p = f()) == NULL

$Id$ -> $FreeBSD$

English fixes: consistent spacing after periods, "userland", not "user land",
other typos, ~four grammar gnits, an ironic case of incorrect
parallelization, bad capitalization, an incorrect use of the
infamous slash ('/'), and an unclear sentence.

Bruce noted that the use of err(), fixed to errx() in the last commit,
did not specify an exit code. This implies the use of either a hand-
rolled err() (Bruce's suggestion) or a random error code (my suggestion),
both of which are against the style guidelines. This commit specifies
the correct error code (implicitly). This also changes the error message
to be a little more helpful.

Use errx() instead of err() in example code calling err() after strtol().

Fix some typos and do some minor mdoc cleanup.

Slightly relax the requirements fro removing extra braces and parenthesis.

Objected to by: bde

oops, remove a dangling predicate left over after a sentence was rewritten.

Add some more macro advice and correct spelling of ``parentheses''.

Added some advice to avoid typedef'ing structures, as this breaks
information-hiding. Also recommended against naming typedefs to end
in _t unless POSIX or ANSI requires it, and in favor of using queue(3)
macros to generate lists rather than rolling one's own.

state that "kernel includes" ==> sys/*.h

An overhaul of style.9 to clear up some of the ambiguities. A number of
things are explicitly stated now rather than being implied by example.

Obtained from: Quite a few people over the last few weeks
Reviewed by: core

Check for -1 instead of EOF in the getopt() example.

Submitted by: Kent Vander Velden

Use the .Fx macro for FreeBSD references for releases prior to 2.0.
Use the .Tn macro for generic FreeBSD references. Cleanup other
formatting problems noticed while making the above changes.

Revert $FreeBSD$ back to $Id$

Make the long-awaited change from $Id$ to $FreeBSD$

This will make a number of things easier in the future, as well as (finally!)
avoiding the Id-smashing problem which has plagued developers for so long.

Boy, I'm glad we're not using sup anymore. This update would have been
insane otherwise.

Sort cross references.

Minor formatting/style fixes.

Submitted by: Sandro Sigala <sandro@cat.local.net> as part of PR # 2134

bring back ``case '?':'' in switch statement

add copyright, $Id$
remove case '?', if '?' is not in getopt(), it should
not be in the switch statement

Restored most of suggestion about using NULL, even though wollman
disagrees with it personally :-), and fixed the misleading parts.

Delete incorrect and misleading suggestion about NULL. I left in
the part about testing pointers against NULL, even though I disagree
with it personally.

Fix some typos.

Correct some man page cross references and file location references.

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.

Add some missing MLINKS, correct some cross references, correct some
file locations and some minor formatting/style problems.

Recreate style with original indent.

Don't use the normal `.Sh' indentation of 5 for the style guide. It
screws up the indentation and the style guide is half about indentation.

Add a slightly edited version of the style document.