From owner-freebsd-doc  Thu Jul 13  9:40: 7 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 7792737BF16
	for <freebsd-doc@freebsd.org>; Thu, 13 Jul 2000 09:40:01 -0700 (PDT)
	(envelope-from gnats@FreeBSD.org)
Received: (from gnats@localhost)
	by freefall.freebsd.org (8.9.3/8.9.2) id JAA34344;
	Thu, 13 Jul 2000 09:40:01 -0700 (PDT)
	(envelope-from gnats@FreeBSD.org)
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>
Reply-To: Tony Finch <dot@dotat.at>
To: FreeBSD-gnats-submit@freebsd.org
X-Send-Pr-Version: 3.2
Subject: docs/19894: confusingly-named punctuation in style(9)
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org


>Number:         19894
>Category:       docs
>Synopsis:       confusingly-named punctuation in style(9)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 13 09:40:01 PDT 2000
>Closed-Date:
>Last-Modified:
>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:
>Unformatted:


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