docs/84850: [patch] strspn(3) manpage description is too esoteric

[Gary W. Swearingen]

>Number:         84850
>Category:       docs
>Synopsis:       [patch] strspn(3) manpage description is too esoteric
>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:   Fri Aug 12 19:00:30 GMT 2005
>Closed-Date:
>Last-Modified:
>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:
>Unformatted: