From owner-freebsd-doc Sat Jul 15 10:30:10 2000 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id 78C6E37BC9F for ; Sat, 15 Jul 2000 10:30:03 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id KAA65137; Sat, 15 Jul 2000 10:30:03 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Date: Sat, 15 Jul 2000 10:30:03 -0700 (PDT) Message-Id: <200007151730.KAA65137@freefall.freebsd.org> To: freebsd-doc@freebsd.org Cc: From: Ben Smithurst Subject: Re: docs/19894: confusingly-named punctuation in style(9) Reply-To: Ben Smithurst Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org The following reply was made to PR docs/19894; it has been noted by GNATS. From: Ben Smithurst To: Sheldon Hearn Cc: Tony Finch , 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 , but not both! includes , and it's okay to depend on that. .Bd -literal -offset 0i -#include /* Non-local includes in brackets. */ +#include /* 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