From owner-freebsd-doc@FreeBSD.ORG Fri Aug 12 19:00:31 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6AB5016A420 for ; Fri, 12 Aug 2005 19:00:31 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id B993443D48 for ; Fri, 12 Aug 2005 19:00:30 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id j7CJ0UIl034374 for ; Fri, 12 Aug 2005 19:00:30 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7CJ0UcB034373; Fri, 12 Aug 2005 19:00:30 GMT (envelope-from gnats) Resent-Date: Fri, 12 Aug 2005 19:00:30 GMT Resent-Message-Id: <200508121900.j7CJ0UcB034373@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, 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 ; 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 ; 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 ; 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" To: FreeBSD-gnats-submit@FreeBSD.org Cc: Subject: docs/84850: [patch] strspn(3) manpage description is too esoteric X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: garys@opusnet.com List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 12 Aug 2005 19:00:31 -0000 >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: