From fanf@hand.dotat.at  Thu Jul 13 09:39:27 2000
Return-Path: <fanf@hand.dotat.at>
Received: from hand.dotat.at (hand.dotat.at [212.240.134.135])
	by hub.freebsd.org (Postfix) with ESMTP id B020237C4B6
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 13 Jul 2000 09:39:25 -0700 (PDT)
	(envelope-from fanf@hand.dotat.at)
Received: from fanf by hand.dotat.at with local (Exim 3.15 #1)
	id 13Cl63-0001v5-00
	for FreeBSD-gnats-submit@freebsd.org; Thu, 13 Jul 2000 15:40:19 +0000
Message-Id: <E13Cl63-0001v5-00@hand.dotat.at>
Date: Thu, 13 Jul 2000 15:40:19 +0000
From: Tony Finch <dot@dotat.at>
Sender: Tony Finch <fanf@hand.dotat.at>
Reply-To: Tony Finch <dot@dotat.at>
To: FreeBSD-gnats-submit@freebsd.org
Subject: confusingly-named punctuation in style(9)
X-Send-Pr-Version: 3.2

>Number:         19894
>Category:       docs
>Synopsis:       confusingly-named punctuation in style(9)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 13 09:40:01 PDT 2000
>Closed-Date:    Sun Jul 16 21:43:41 BST 2000
>Last-Modified:  Sun Jul 16 21:49:20 BST 2000
>Originator:     Tony Finch <dot@dotat.at>
>Release:        FreeBSD 4.0-STABLE-20000705 i386
>Organization:
dotat
>Environment:

	*BSD since the year dot, it seems

>Description:

In the section about usage() and manual page synopsys lines, the
text refers to what I call "square brackets" as "braces". I think
this is confusing and should be changed according to the diff below.
This also makes it consistent with the Jargon File.

>How-To-Repeat:


>Fix:

--- /usr/src/share/man/man9/style.9.orig	Thu Jul 13 15:31:22 2000
+++ /usr/src/share/man/man9/style.9	Thu Jul 13 15:31:03 2000
@@ -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
-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.  Options
+without operands come first, in alphabetical order inside a single set of
+square brackets, followed by options with operands, in alphabetical
+order, each in square brackets, followed by required arguments in the
+order they are specified, not in brackets, followed by optional
+arguments in the order they are specified, in square 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 square brackets.
 .Pp
 .Bd -ragged -offset 0.3i
 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"

>Release-Note:
>Audit-Trail:

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Tony Finch <dot@dotat.at>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/19894: confusingly-named punctuation in style(9) 
Date: Thu, 13 Jul 2000 19:05:36 +0200

 On Thu, 13 Jul 2000 15:40:19 GMT, Tony Finch wrote:
 
 > In the section about usage() and manual page synopsys lines, the
 > text refers to what I call "square brackets" as "braces". I think
 > this is confusing and should be changed according to the diff below.
 > This also makes it consistent with the Jargon File.
 
 I agree that the text as is, is wrong.  However, I think the correct
 names for these things should be used:
 
 	parentheses	(	)
 	braces		{	}
 	brackets	[	]
 
 Ciao,
 Sheldon.
 

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--
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: Tony Finch <dot@dotat.at>, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/19894: confusingly-named punctuation in style(9) 
Date: Sun, 16 Jul 2000 16:52:42 +0200

 On Sat, 15 Jul 2000 17:55:51 +0100, Ben Smithurst wrote:
 
 >  .Pp
 > -Usage statements should look like the manual pages synopsis.  Options w/o
 > +Usage statements should look like the manual pages synopsis.  Options without
 
 Break that sentence off onto its own new line. :-)
 
 Usage statements should look like the manual pages synopsis.
 Options without
 
 >  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 order they
 > +are specified, in brackets.  A bar
 
 There's another too-long line in here, again the symptom of poor line
 breaking.  Each sentence should begin on its own line, and sentences
 which don't fit on a single line (<72 chars) should be broken on
 sentence fragments if possible:
 
 Options without operands come first, in alphabetical order
 inside a single set of 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 order they are specified,
 in brackets.
 A bar
 [...]
 
 This is awful English.  I think it might be better to do this as a
 bullet list.  But now we're moving further from the original problem.
 It often happens like this, especially with manual pages that receive
 lots of piecemeal updates.  ;-)
 
 Ciao,
 Sheldon.
 

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 /
 

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 18:48:38 +0100

 Sheldon Hearn wrote:
 
 >> -Usage statements should look like the manual pages synopsis.  Options w/o
 >> +Usage statements should look like the manual pages synopsis.  Options without
 > 
 > Break that sentence off onto its own new line. :-)
 
 Doh!
 
 <excuse quality=weak> I was trying to change as few lines as possible to
 make the diff easier to read... </excuse>
 
 > Options without operands come first, in alphabetical order
 > inside a single set of 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 order they are specified,
 > in brackets.
 
 That's one long sentence. :-(
 
 > I think it might be better to do this as a bullet list.
 
 I guess that's an excuse for me to learn how to do bullet lists in mdoc.
 :-) mdoc.samples should explain all, I hope...
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/19894: confusingly-named punctuation in style(9) 
Date: Sun, 16 Jul 2000 22:18:49 +0200

 On Sun, 16 Jul 2000 19:01:47 +0100, Ben Smithurst wrote:
 
 > > I think it might be better to do this as a bullet list.
 > 
 > ok, my first diff for that:
 
 Your patch is good.  I would consider placeing a paragraph marker (Pp)
 before the -compact list.  Also, I'd leave out this one line:
 
 > +Any required arguments should not be within brackets.
 
 I don't think it adds anything.  I don't feel very strongly about this.
 
 Good job.
 
 Ciao,
 Sheldon.
 
 
 
State-Changed-From-To: open->closed 
State-Changed-By: ben 
State-Changed-When: Sun Jul 16 21:43:41 BST 2000 
State-Changed-Why:  
Committed in -current, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=19894 
>Unformatted:
