Date: Sat, 15 Jul 2000 10:30:03 -0700 (PDT) From: Ben Smithurst <ben@FreeBSD.org> To: freebsd-doc@freebsd.org Subject: Re: docs/19894: confusingly-named punctuation in style(9) Message-ID: <200007151730.KAA65137@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/19894; it has been noted by GNATS.
From: Ben Smithurst <ben@FreeBSD.org>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: Tony Finch <dot@dotat.at>, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/19894: confusingly-named punctuation in style(9)
Date: Sat, 15 Jul 2000 17:55:51 +0100
--yhze8HlyfmXt1APY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
Sheldon Hearn wrote:
> I agree that the text as is, is wrong. However, I think the correct
> names for these things should be used:
> =20
> parentheses ( )
> braces { }
> brackets [ ]
Probably. I think saying "square brackets" would make it clearer (I
suspect a lot of people think of "(" and ")" as "brackets"), but since
an example is given anyway I suppose just "brackets" is adequate.
How about this then? I found one other thing which I think should be
fixed while I'm there...
--- style.9 2000/03/19 16:52:59 1.33
+++ style.9 2000/07/15 16:51:19
@@ -56,7 +56,7 @@
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. */
+#include <sys/types.h> /* Non-local includes in angle brackets. */
.Ed
.Pp
If it's a network program, put the network include files next.
@@ -470,16 +470,16 @@
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 synopsis. Options w/o
+Usage statements should look like the manual pages synopsis. Options with=
out
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
+brackets, followed by options with operands, in alphabetical order,
+each in brackets, followed by required arguments in the order they
+are specified, not in brackets, followed by optional arguments in the orde=
r they
+are specified, in brackets. 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.
+placed in a single set of brackets.
.Pp
.Bd -ragged -offset 0.3i
"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
--=20
Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
FreeBSD Documentation Project /
--yhze8HlyfmXt1APY
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
MessageID: P1raC1Go5DaYt+yswBYZKrTtrGOxGi2j
iQCVAwUBOXCXlysPVtiZOS99AQHFGwP+NZ3hfh89yyFdj/UfV727K91KP5hRkVaA
PVAXOSFysscX+yoZXTppe7Gtywe2VmF4BII2aEcOdUMshGnZvCbZ7bGvOZuKXX3Q
Wa+ETGL4iTcBnzDPF1r5HAUmiA+bECK65/Oea4gfpRaACOSV67Ze4JWT6UCxAMOi
w+bovgY5mqQ=
=AJZN
-----END PGP SIGNATURE-----
--yhze8HlyfmXt1APY--
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200007151730.KAA65137>