From garys@opusnet.com  Fri Aug 12 18:52:59 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id D6B4A16A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 12 Aug 2005 18:52:59 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 7977143D53
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 12 Aug 2005 18:52:59 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id A0092C8B00EC; Fri, 12 Aug 2005 11:52:57 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7CItZaZ033611
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 12 Aug 2005 11:55:35 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7CItU0A033610;
	Fri, 12 Aug 2005 11:55:30 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <43br43yogt.r43@mail.opusnet.com>
Date: Fri, 12 Aug 2005 11:55:30 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] strspn(3) manpage description is too esoteric
X-GNATS-Notify:

>Number:         84850
>Category:       docs
>Synopsis:       [patch] strspn(3) manpage description is too esoteric
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    garys
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Aug 12 19:00:30 GMT 2005
>Closed-Date:    Wed Sep 07 17:51:57 GMT 2005
>Last-Modified:  Wed Sep 07 17:51:57 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

The strspn(3) description does not help those who need a description.

The term "span" is too esoteric and even after I determined what the
function does, I'm still not sure whether it's meaningful to say that
the function "spans" something, when it just computes a number. Even
if I understand what the function returns, I'm left wondering whether
"spanning" is a side-effect of the function I should also understand.
(The source code shows that spanning is not a side effect, of course.)

Similarly for strcspn(3).

>How-To-Repeat:
n/a

>Fix:

Leave the existing text alone for traditionalists, but add to the
DESCRIPTION.

Except also make it refer to both strings the same way.

AFAIK (not far), the new text is compatible with multi-byte
characters, but that should be considered by reviewers.


--- strspn..orig.3	Sat Aug  6 08:30:49 2005
+++ strspn.3	Sat Aug  6 08:42:20 2005
@@ -56,8 +56,15 @@
 .Fa s
 as long as the characters from
 .Fa s
-occur in string
+occur in the null-terminated string
 .Fa charset .
+In other words, it computes the string array index in
+.Fa s
+of the first character of
+.Fa s
+which is not in
+.Fa charset ,
+else the index of the first null character.
 .Sh RETURN VALUES
 The
 .Fn strspn


--- strcspn..orig.3	Sat Aug  6 08:30:46 2005
+++ strcspn.3	Sat Aug  6 08:42:24 2005
@@ -63,6 +63,13 @@
 .Em complement
 of
 .Fa charset ) .
+In other words, it computes the string array index in
+.Fa s
+of the first character of
+.Fa s
+which is also in
+.Fa charset ,
+else the index of the first null character.
 .Sh RETURN VALUES
 The
 .Fn strcspn
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->garys 
Responsible-Changed-By: garys 
Responsible-Changed-When: Sun Aug 28 23:45:37 GMT 2005 
Responsible-Changed-Why:  
Ready to get review and approval. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84850 
State-Changed-From-To: open->patched 
State-Changed-By: garys 
State-Changed-When: Tue Aug 30 13:01:12 GMT 2005 
State-Changed-Why:  
Patched in HEAD. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84850 
State-Changed-From-To: patched->closed 
State-Changed-By: garys 
State-Changed-When: Wed Sep 7 17:51:17 GMT 2005 
State-Changed-Why:  
Two files patched in HEAD, RELENG_6, RELENG_5. 

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