From swear@attbi.com  Thu Jan 30 20:51:58 2003
Return-Path: <swear@attbi.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 837D937B401
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 20:51:58 -0800 (PST)
Received: from sccrmhc03.attbi.com (sccrmhc03.attbi.com [204.127.202.63])
	by mx1.FreeBSD.org (Postfix) with ESMTP id A090D43F9B
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 20:51:57 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: from localhost.localdomain (unknown[12.242.158.67])
          by sccrmhc03.attbi.com (sccrmhc03) with ESMTP
          id <2003013104515100300ju1kre>; Fri, 31 Jan 2003 04:51:51 +0000
Received: from localhost.localdomain (localhost [127.0.0.1])
	by localhost.localdomain (8.12.6/8.12.5) with ESMTP id h0V4pM5F011702
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 30 Jan 2003 20:51:23 -0800 (PST)
	(envelope-from swear@attbi.com)
Received: (from jojo@localhost)
	by localhost.localdomain (8.12.6/8.12.5/Submit) id h0V4pH6s011699;
	Thu, 30 Jan 2003 20:51:17 -0800 (PST)
	(envelope-from swear@attbi.com)
Message-Id: <lhn0lhj516.0lh@localhost.localdomain>
Date: 30 Jan 2003 20:51:17 -0800
From: "Gary W. Swearingen" <swear@attbi.com>
Reply-To: swear@attbi.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: wc(1) manpage has poor explanations.
X-GNATS-Notify:

>Number:         47705
>Category:       docs
>Synopsis:       wc(1) manpage has poor explanations.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jan 30 21:00:24 PST 2003
>Closed-Date:    Wed Feb 23 22:41:39 GMT 2005
>Last-Modified:  Wed Feb 23 22:41:39 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.7-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

1) The wc(1) manpage has poor explanations, particularly the definitions of
lines and words.

2) The manpage doesn't explain that only the latter of -c & -m is used.

3) The first paragraph is too big and unorganized. (Better to give
general description, then explanations of lines, words, chararacters.)

4) The manpage refers users to a programmer's manpage.  (Better to just
say what the command does, since it's not hard.  A second reference to
the programmer's manpage can be left in the COMPATIBILITY section and
there's no longer any need for a "See Also" section.)

5) There are several other minor problems. (See patch.)
================
>How-To-Repeat:
n/a
================
>Fix:

Patch this:
.\" $FreeBSD: src/usr.bin/wc/wc.1,v 1.6.2.4 2002/08/25 02:47:04 tjr Exp $
with this:

--- /pr/work/wc..orig.1	Thu Jan 30 18:40:13 2003
+++ /pr/work/wc.1	Thu Jan 30 20:28:54 2003
@@ -48,35 +48,47 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility displays the number of lines, words, and bytes contained in each
+utility displays the number of lines, words,
+bytes (or characters), and filename of each
 input
 .Ar file
-(or standard input, by default) to the standard output.
-A line is defined as a string of characters delimited by a <newline>
-character,
-and a word is defined as a string of characters delimited by white space
-characters.
-White space characters are the set of characters for which the
-.Xr isspace 3
-function returns true.
-If more than one input file is specified, a line of cumulative counts
-for all the files is displayed on a separate line after the output for
-the last file.
+to the standard output (on separate lines), except that if
+.Ar file
+is not specified,
+then standard input is counted and there is no filename output.
+If more than one input file is specified,
+a line of cumulative counts for all the files is displayed
+on a separate line after the output for the last file.
+.Pp
+A line is defined as a <newline> character.
+Beware that characters following the last <newline>
+are not included in the line count.
+A word is defined as a string of non-whitespace characters
+separated by whitespace characters.
+Whitespace characters are <space>, <horizontal-tab>, <carriage-return>,
+<newline>, <vertical-tab>, and <newpage>.
+A character is normally one byte but might be multiple bytes,
+depending upon the environment.
+(See the ENVIRONMENT section.)
 .Pp
 The following options are available:
 .Bl -tag -width Ds
 .It Fl c
 The number of bytes in each input file
 is written to the standard output.
+This cancels any prior
+.Fl w .
 .It Fl l
 The number of lines in each input file
 is written to the standard output.
 .It Fl m
 The number of characters in each input file is written to the standard output.
-If the current locale does not support multibyte characters, this
+If the environment does not support multi-byte characters, this
 is equivalent to the
 .Fl c
 option.
+This cancels any prior
+.Fl c .
 .It Fl w
 The number of words in each input file
 is written to the standard output.
@@ -85,15 +97,13 @@
 When an option is specified,
 .Nm
 only reports the information requested by that option.
+The order of output is always: line, word, byte/character, filename.
 The default action is equivalent to specifying the
 .Fl c ,
 .Fl l
 and
 .Fl w
 options.
-.Pp
-If no files are specified, the standard input is used and no
-file name is displayed.
 .Sh ENVIRONMENT
 The
 .Ev LANG ,
@@ -104,18 +114,18 @@
 .Nm
 as described in
 .Xr environ 7 .
+For more information,
+see the FreeBSD Handbook's discussion of locale setting.
 .Sh EXAMPLES
-Count the number of characters, words and lines in each of the files
+Count the number of lines, words, and characters in each of the files
 .Pa report1
 and
 .Pa report2
 as well as the totals for both:
 .Pp
-.Dl "wc -mlw report1 report2"
+.Dl "wc -lwm report1 report2"
 .Sh DIAGNOSTICS
 .Ex -std
-.Sh SEE ALSO
-.Xr isspace 3
 .Sh COMPATIBILITY
 Historically, the
 .Nm
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 23 06:20:47 GMT 2005 
State-Changed-Why:  
Different version of the patch committed, we cannot remove the SEE ALSO section when it's useful. 
I've also made some other minor changes.  Thanks! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Feb 23 06:20:47 GMT 2005 
Responsible-Changed-Why:  
Over to me, MFC pending. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=47705 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 23 22:41:17 GMT 2005 
State-Changed-Why:  
MFC complete, switch to closed. 

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