From owner-freebsd-doc  Sun Jul 16 11:10: 9 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 7DF1A37B7B8
	for <freebsd-doc@freebsd.org>; Sun, 16 Jul 2000 11:10:03 -0700 (PDT)
	(envelope-from gnats@FreeBSD.org)
Received: (from gnats@localhost)
	by freefall.freebsd.org (8.9.3/8.9.2) id LAA60699;
	Sun, 16 Jul 2000 11:10:03 -0700 (PDT)
	(envelope-from gnats@FreeBSD.org)
Date: Sun, 16 Jul 2000 11:10:03 -0700 (PDT)
Message-Id: <200007161810.LAA60699@freefall.freebsd.org>
To: freebsd-doc@freebsd.org
Cc: 
From: Ben Smithurst <ben@FreeBSD.org>
Subject: Re: docs/19894: confusingly-named punctuation in style(9)
Reply-To: Ben Smithurst <ben@FreeBSD.org>
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 <ben@FreeBSD.org>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/19894: confusingly-named punctuation in style(9)
Date: Sun, 16 Jul 2000 19:01:47 +0100

 Sheldon Hearn wrote:
 
 > I think it might be better to do this as a bullet list.
 
 ok, my first diff for that:
 
 Index: style.9
 ===================================================================
 RCS file: /usr/cvs/src/share/man/man9/style.9,v
 retrieving revision 1.33
 diff -u -r1.33 style.9
 --- style.9	2000/03/19 16:52:59	1.33
 +++ style.9	2000/07/16 17:54:00
 @@ -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,35 @@
  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
 -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
 +Usage statements should look like the manual pages synopsis.
 +The usage statement should be structured in the following order:
 +.Bl -enum -compat
 +.It
 +Options without operands come first,
 +in alphabetical order,
 +inside a single set of brackets.
 +.It
 +Options with operands come next,
 +also in alphabetical order,
 +with each option and its argument inside its own pair of brackets.
 +.It
 +Required arguments
 +.Pq if any
 +are next,
 +listed in the order they should be specified in the command line.
 +Any required arguments should not be within brackets.
 +.It
 +Finally,
 +any optional arguments should be listed,
 +listed in the order they should be specified,
 +and all inside brackets.
 +.El
 +.Pp
 +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"
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message