bin/46103: The banner(6) manpage, as well as the program's `usage' line, could use improvement

[bughunting%xs4all.nl@localhost]

>Number:         46103
>Category:       bin
>Synopsis:       The banner(6) manpage, as well as the program's `usage' line, 
>could use improvement
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Feb 26 20:55:00 +0000 2012
>Originator:     Bug Hunting
>Release:        NetBSD-current (6.99.3)
>Organization:
>Environment:
>Description:
The banner(6) manpage and the program's `usage' line are inconsistent.
Also, the manpage could use other improvements, including adding
`EXIT STATUS' and `SEE ALSO' sections, as well as putting the example already
included in it, although a bit altered with the patch below as well, in an
`EXAMPLES' section of its own.
>How-To-Repeat:
Show the manpage:
   $ man 6 banner
   [output omitted]

Show the manpage's incorrect (the ``message'' argument is optional, and if it's
given, there is only one anyway) `SYNOPSIS' section:
   $ man -s 6 -h banner
   banner [-w width] message ...

Print the program's incorrect (the ``message'' argument is missing) 
`usage'-line,
using a non-existent option:
   $ /usr/games/banner -q
   banner: unknown option -- q
   usage: banner [-w width]
>Fix:
Apply the following proposed patch (the MD5-sum of this patch is
fbb4d493dc39945a42d3568bf0a83261, please verify it before applying;
also, please re-alter the date in the `.Dd' (which was changed here explicitly
because of non-trivial changes) macro when needed):

Index: games/banner/banner.6
===================================================================
RCS file: /cvsroot/src/games/banner/banner.6,v
retrieving revision 1.17
diff -u -r1.17 banner.6
--- games/banner/banner.6       14 May 2010 19:02:28 -0000      1.17
+++ games/banner/banner.6       26 Feb 2012 19:12:02 -0000
@@ -29,32 +29,43 @@
 .\"
 .\"    @(#)banner.6    8.2 (Berkeley) 4/29/95
 .\"
-.Dd December 14, 2006
+.Dd February 26, 2012
 .Dt BANNER 6
 .Os
 .Sh NAME
 .Nm banner
-.Nd print large banner on printer
+.Nd print large banners
 .Sh SYNOPSIS
 .Nm
 .Op Fl w Ar width
-.Ar message ...
+.Op Ar message
 .Sh DESCRIPTION
 .Nm
-prints a large, high quality banner on the standard output.
-If the message is omitted, it prompts for and
-reads one line of its standard input.
+prints a large, high quality banner on standard output.
+If
+.Ar message
+is omitted, one line of standard input is read for it.
+A prompt is written to standard error in case standard input is
+connected to a terminal.
+.Pp
 If
 .Fl w
-is given, the output is scrunched down from a width of 132 to
+is given, the output is scrunched down from a width of 132 (the default) to
 .Ar width ,
 suitable for a narrow terminal.
-For example:
-.Pp
-.Dl "/usr/games/banner -w 80 Hello"
 .Pp
 The output should be printed on paper of the appropriate width,
 with no breaks between the pages.
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+The following command will print the current date as a banner on
+standard output, using a width of 80:
+.Pp
+.Dl "/usr/games/banner -w 80 `date`"
+.Sh SEE ALSO
+.Xr banner 1 ,
+.Xr lpr 1
 .Sh AUTHORS
 .An Mark Horton
 .Sh BUGS
Index: games/banner/banner.c
===================================================================
RCS file: /cvsroot/src/games/banner/banner.c,v
retrieving revision 1.19
diff -u -r1.19 banner.c
--- games/banner/banner.c       29 Aug 2011 20:30:36 -0000      1.19
+++ games/banner/banner.c       26 Feb 2012 19:12:03 -0000
@@ -45,7 +45,7 @@
 
 /*
  * banner - prints large signs
- * banner [-w width] [-d] [-t] message ...
+ * banner [-dt] [-w width] [message]
  */
 
 #include <err.h>
@@ -1051,7 +1051,7 @@
                        break;
                case '?':
                default:
-                       (void)fprintf(stderr, "usage: banner [-w width]\n");
+                       (void)fprintf(stderr, "usage: banner [-w width] 
[message]\n");
                        exit(1);
                }
        argc -= optind;