[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openbsd-bugs
Subject:    Re: [PATCH 1/3] Add missing clear(1) man page
From:       Jason McIntyre <jmc () kerhand ! co ! uk>
Date:       2024-04-27 15:06:20
Message-ID: Zi0UbEGHwX3G2KMs () manila ! kerhand ! co ! uk
[Download RAW message or body]

thanks, have committed this.
jmc

On Wed, Apr 24, 2024 at 02:09:13AM +0200, Piotr Durlej wrote:
> ---
>  usr.bin/tput/Makefile |   1 +
>  usr.bin/tput/clear.1  | 163 ++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 164 insertions(+)
>  create mode 100644 usr.bin/tput/clear.1
> 
> diff --git a/usr.bin/tput/Makefile b/usr.bin/tput/Makefile
> index 7b261e36c7f..c966ab1acee 100644
> --- a/usr.bin/tput/Makefile
> +++ b/usr.bin/tput/Makefile
> @@ -11,6 +11,7 @@ TIC= ${.CURDIR}/../tic
>  CFLAGS+= -I${CURSES} -I${TIC} -I${.CURDIR} -I.
>  .PATH:  ${TIC}
>  CLEANFILES+= termsort.h
> +MAN+=	clear.1
>  
>  termsort.h: ${TIC}/MKtermsort.sh
>  	sh ${TIC}/MKtermsort.sh awk ${CURSES}/Caps > ${.TARGET}
> diff --git a/usr.bin/tput/clear.1 b/usr.bin/tput/clear.1
> new file mode 100644
> index 00000000000..c5184de779c
> --- /dev/null
> +++ b/usr.bin/tput/clear.1
> @@ -0,0 +1,163 @@
> +.\"***************************************************************************
> +.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
> +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
> +.\"                                                                          *
> +.\" Permission is hereby granted, free of charge, to any person obtaining a  *
> +.\" copy of this software and associated documentation files (the            *
> +.\" "Software"), to deal in the Software without restriction, including      *
> +.\" without limitation the rights to use, copy, modify, merge, publish,      *
> +.\" distribute, distribute with modifications, sublicense, and/or sell       *
> +.\" copies of the Software, and to permit persons to whom the Software is    *
> +.\" furnished to do so, subject to the following conditions:                 *
> +.\"                                                                          *
> +.\" The above copyright notice and this permission notice shall be included  *
> +.\" in all copies or substantial portions of the Software.                   *
> +.\"                                                                          *
> +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
> +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
> +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
> +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
> +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
> +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
> +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
> +.\"                                                                          *
> +.\" Except as contained in this notice, the name(s) of the above copyright   *
> +.\" holders shall not be used in advertising or otherwise to promote the     *
> +.\" sale, use or other dealings in this Software without prior written       *
> +.\" authorization.                                                           *
> +.\"***************************************************************************
> +.\"
> +.\" $Id: clear.1,v 1.27 2022/02/12 20:07:29 tom Exp $
> +.TH clear 1 ""
> +.\" these would be fallbacks for DS/DE,
> +.\" but groff changed the meaning of the macros.
> +.de NS
> +.ie n  .sp
> +.el    .sp .5
> +.ie n  .in +4
> +.el    .in +2
> +.nf
> +.ft C			\" Courier
> +..
> +.de NE
> +.fi
> +.ft R
> +.ie n  .in -4
> +.el    .in -2
> +..
> +.ie \n(.g .ds `` \(lq
> +.el       .ds `` ``
> +.ie \n(.g .ds '' \(rq
> +.el       .ds '' ''
> +.de bP
> +.ie n  .IP \(bu 4
> +.el    .IP \(bu 2
> +..
> +.ds n 5
> +.SH NAME
> +\fBclear\fP \- clear the terminal screen
> +.SH SYNOPSIS
> +\fBclear\fR [\fB\-T\fItype\fR] [\fB\-V\fR] [\fB\-x\fR]
> +.br
> +.SH DESCRIPTION
> +\fBclear\fP clears your terminal's screen if this is possible,
> +including the terminal's scrollback buffer
> +(if the extended \*(``E3\*('' capability is defined).
> +\fBclear\fP looks in the environment for the terminal type
> +given by the environment variable \fBTERM\fP,
> +and then in the
> +\fBterminfo\fP database to determine how to clear the screen.
> +.PP
> +\fBclear\fP writes to the standard output.
> +You can redirect the standard output to a file (which prevents
> +\fBclear\fP from actually clearing the screen),
> +and later \fBcat\fP the file to the screen, clearing it at that point.
> +.SH OPTIONS
> +.PP
> +.TP 5
> +.B \-T \fItype\fP
> +indicates the \fItype\fP of terminal.
> +Normally this option is
> +unnecessary, because the default is taken from the environment
> +variable \fBTERM\fP.
> +If \fB\-T\fP is specified, then the shell
> +variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored.
> +.TP
> +.B \-V
> +reports the version of ncurses which was used in this program, and exits.
> +The options are as follows:
> +.TP
> +.B \-x
> +do not attempt to clear the terminal's scrollback buffer
> +using the extended \*(``E3\*('' capability.
> +.SH HISTORY
> +A \fBclear\fP command appeared in 2.79BSD dated February 24, 1979.
> +Later that was provided in Unix 8th edition (1985).
> +.PP
> +AT&T adapted a different BSD program (\fBtset\fP) to make
> +a new command (\fBtput\fP),
> +and used this to replace the \fBclear\fP command with a shell script
> +which calls \fBtput clear\fP, e.g.,
> +.NS
> +/usr/bin/tput ${1:+-T$1} clear 2> /dev/null
> +exit
> +.NE
> +.PP
> +In 1989, when Keith Bostic revised the BSD \fBtput\fP command
> +to make it similar to the AT&T \fBtput\fP,
> +he added a shell script for the \fBclear\fP command:
> +.NS
> +exec tput clear
> +.NE
> +.PP
> +The remainder of the script in each case is a copyright notice.
> +.PP
> +The ncurses \fBclear\fP command began in 1995 by adapting the original
> +BSD \fBclear\fP command (with terminfo, of course).
> +.PP
> +The \fBE3\fP extension came later:
> +.bP
> +In June 1999, \fBxterm\fP provided an extension to the standard control
> +sequence for clearing the screen.
> +Rather than clearing just the visible part of the screen using
> +.NS
> +printf '\\033[2J'
> +.NE
> +.IP
> +one could clear the \fIscrollback\fP using
> +.NS
> +printf '\\033[\fB3\fPJ'
> +.NE
> +.IP
> +This is documented in \fIXTerm Control Sequences\fP as a feature originating
> +with \fBxterm\fP.
> +.bP
> +A few other terminal developers adopted the feature, e.g., PuTTY in 2006.
> +.bP
> +In April 2011, a Red Hat developer submitted a patch to the Linux
> +kernel, modifying its console driver to do the same thing.
> +The Linux change, part of the 3.0 release, did not mention \fBxterm\fP,
> +although it was cited in the Red Hat bug report (#683733)
> +which led to the change.
> +.bP
> +Again, a few other terminal developers adopted the feature.
> +But the
> +next relevant step was a change to the \fBclear\fP program in 2013
> +to incorporate this extension.
> +.bP
> +In 2013, the \fBE3\fP extension was overlooked in \fBtput\fP with
> +the \*(``clear\*('' parameter.
> +That was addressed in 2016 by reorganizing \fBtput\fP to share
> +its logic with \fBclear\fP and \fBtset\fP.
> +.SH PORTABILITY
> +Neither IEEE Std 1003.1/The Open  Group  Base  Specifications  Issue  7
> +(POSIX.1-2008) nor X/Open Curses Issue 7 documents tset or reset.
> +.PP
> +The latter documents \fBtput\fP, which could be used to replace this utility
> +either via a shell script or by an alias (such as a symbolic link) to
> +run \fBtput\fP as \fBclear\fP.
> +.SH SEE ALSO
> +\fBtput\fP(1), \fBterminfo\fP(\*n), \fBxterm\fP(1).
> +.PP
> +This describes \fBncurses\fP
> +version 6.4 (patch 20221231).
> -- 
> 2.44.0
> 

[prev in list] [next in list] [prev in thread] [next in thread]