From garys@opusnet.com  Mon Aug  8 15:37:55 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 3A46D16A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  8 Aug 2005 15:37:55 +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 DDE6143D48
	for <FreeBSD-gnats-submit@freebsd.org>; Mon,  8 Aug 2005 15:37:54 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AC5190290096; Mon, 08 Aug 2005 08:37:53 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j78Fe3iH038100
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 8 Aug 2005 08:40:03 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j78Fdwj0038099;
	Mon, 8 Aug 2005 08:39:58 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <e0hde0jv3l.de0@mail.opusnet.com>
Date: Mon, 08 Aug 2005 08:39:58 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: [patch] tput(1) manpage missing ENVIRONMENT section with TERM, etc
X-GNATS-Notify:

>Number:         84670
>Category:       docs
>Synopsis:       [patch] tput(1) manpage missing ENVIRONMENT section with TERM, etc
>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:   Mon Aug 08 15:40:19 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:
tput(1) manpage has several problems:

-- Missing an ENVIRONMENT section with TERM.
-- Too much in first paragraph, including start of option description.
-- A couple of descriptions are incomplete.
-- Confuses a "sequence" (of fields) with a "capability" (one field).
-- Synopsis doesn't show that all arguments are optional.

>How-To-Repeat:
n/a

>Fix:

--- tput..orig.1	Thu Aug  4 17:17:56 2005
+++ tput.1	Thu Aug  4 19:21:31 2005
@@ -42,22 +42,24 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl T Ar term
-.Ar attribute ...
+.Op Ar attribute ...
 .Nm clear
 .Sh DESCRIPTION
 The
 .Nm
 utility makes terminal-dependent information available to users or shell
 applications.
-When invoked as the
+.Pp
+The
 .Nm clear
-utility, the screen will be cleared as if
+utility executes the
 .Dl tput clear
-had been executed.
-The options to
+command, ignoring any arguments.
+.Pp
+The only option to
 .Nm
-are as follows:
-.Bl -tag -width Ds
+is:
+.Bl -tag -width 2n
 .It Fl T
 The terminal name as specified in the
 .Xr termcap 5
@@ -69,7 +71,9 @@
 .Nm
 retrieves the
 .Dq Ev TERM
-variable from the environment.
+variable from the environment unless that too is not specified,
+in which case an error message will be sent to standard error and
+the error status will be 2.
 .El
 .Pp
 The
@@ -87,28 +91,37 @@
 is of type string, and takes arguments (e.g.\& cursor movement,
 the termcap
 .Dq cm
-sequence) the arguments are taken from the command line immediately
+capability) the arguments are taken from the command line immediately
 following the attribute.
 .Pp
-The following special attributes are available:
+The following special attributes are available.
+The first three use the capabilities of the specified terminal,
+and only work if compatible with the utility's terminal.
 .Bl -tag -width Ar
 .It Cm clear
 Clear the screen (the
 .Xr termcap 5
 .Dq cl
-sequence).
+capability).
 .It Cm init
 Initialize the terminal (the
 .Xr termcap 5
 .Dq is
-sequence).
-.It Cm longname
-Print the descriptive name of the user's terminal type.
+capability).
 .It Cm reset
 Reset the terminal (the
 .Xr termcap 5
 .Dq rs
-sequence).
+capability).
+.It Cm longname
+Print the descriptive name of the user's terminal type.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width ".Ev TERM"
+.It Ev TERM
+The terminal name, if set and
+.Fl T
+is not used.
 .El
 .Sh DIAGNOSTICS
 The exit status of
@@ -116,16 +129,28 @@
 is as follows:
 .Bl -tag -width indent
 .It 0
-If the last attribute
+If the last
 .Ar attribute
-argument is of type string or integer, its value was successfully written
+is of type string or integer, its value was successfully written
 to standard output.
-If the argument is of type boolean, the terminal has this attribute.
+If the
+.Ar attribute
+is of type boolean, the terminal does have the
+.Ar attribute .
+Otherwise, no
+.Ar attribute
+was specified.
 .It 1
-This terminal does not have the specified boolean
+If the last
+.Ar attribute
+is of type boolean,
+this terminal does not have the
 .Ar attribute .
 .It 2
 Usage error.
+For example, see
+.Fl T
+description.
 .It 3
 No information is available about the specified terminal type.
 .El
>Release-Note:
>Audit-Trail:
>Unformatted:
