diff options
Diffstat (limited to 'upstream/archlinux/man1/clear.1')
| -rw-r--r-- | upstream/archlinux/man1/clear.1 | 225 |
1 files changed, 123 insertions, 102 deletions
diff --git a/upstream/archlinux/man1/clear.1 b/upstream/archlinux/man1/clear.1 index 4784975d..9301043a 100644 --- a/upstream/archlinux/man1/clear.1 +++ b/upstream/archlinux/man1/clear.1 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,139 +27,160 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: clear.1,v 1.29 2023/04/09 08:28:00 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 '' '' +.\" $Id: clear.1,v 1.48 2024/03/16 15:35:01 tom Exp $ +.TH clear 1 2024-03-16 "ncurses 6.5" "User commands" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ie t .ds ' \(aq +.el .ds ' ' +.\} +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. -.ds n 5 +. .SH NAME -\fBclear\fP \- clear the terminal screen +\fB\%clear\fP \- +clear the terminal screen .SH SYNOPSIS -\fBclear\fR [\fB\-T\fItype\fR] [\fB\-V\fR] [\fB\-x\fR] -.br +.B clear +.RB [ \-x ] +.RB [ \-T\ \c +.IR terminal-type ] +.PP +.B "clear \-V" .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. +\fB\%clear\fP clears your terminal's screen and its scrollback buffer, +if any. +\fB\%clear\fP retrieves the terminal type from the environment +variable \fITERM\fP, +then consults the \fIterminfo\fP terminal capability database entry for +that type to determine how to perform these actions. .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. +The capabilities to clear the screen and scrollback buffer are named +\*(``clear\*('' and \*(``E3\*('', respectively. +The latter is a \fIuser-defined capability\fP, +applying an extension mechanism introduced in \fI\%ncurses\fP 5.0 +(1999). .SH OPTIONS -.PP -.TP 5 +\fB\%clear\fP recognizes the following options. +.TP 9 \" "-T type" + 2n .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. +produces instructions suitable for the terminal \fItype\fP. +Normally, +this option is unnecessary, +because the terminal type is inferred from the environment variable +\fITERM\fP. +If this option is specified, +\fB\%clear\fP ignores the environment variables \fILINES\fP and +\fI\%COLUMNS\fP as well. .TP .B \-V -reports the version of ncurses which was used in this program, and exits. -The options are as follows: +reports the version of \fI\%ncurses\fP associated with this program and +exits with a successful status. .TP .B \-x -do not attempt to clear the terminal's scrollback buffer -using the extended \*(``E3\*('' capability. +prevents \fB\%clear\fP from attempting to clear the scrollback buffer. +.SH PORTABILITY +Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 +(POSIX.1-2008) nor X/Open Curses Issue 7 documents \fB\%clear\fP. +.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 \fB\%tput\fP as \fB\%clear\fP. .SH HISTORY -A \fBclear\fP command appeared in 2.79BSD dated February 24, 1979. -Later that was provided in Unix 8th edition (1985). +A \fBclear\fP command using the \fItermcap\fP database and library +appeared in 2BSD (1979). +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c +Eighth Edition Unix (1985) later included it. +.PP +The commercial Unix arm of AT&T adapted a different BSD program +(\fBtset\fP) to make a new command, +\fBtput\fP, +and replaced the \fBclear\fP program with a shell script that called +\*(``\fBtput clear\fP\*(''. .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 +.RS 4 +.EX +/usr/bin/tput ${1:+\-T$1} clear 2> /dev/null exit -.NE +.EE +.RE .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 +to make it similar to AT&T's \fBtput\fP, +he added a \fBclear\fP shell script as well. +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\ +.\" tput/clear.sh +.PP +.RS 4 +.EX exec tput clear -.NE +.EE +.RE .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: +In 1995, +\fI\%ncurses\fP's \fBclear\fP began by adapting BSD's original +\fBclear\fP command to use \fIterminfo\fP. +The \fBE3\fP extension came later. .bP -In June 1999, \fBxterm\fP provided an extension to the standard control +In June 1999, \fIxterm\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 +.RS 8 +.PP +.EX +printf \*'\e033[2J\*' +.EE +.RE .IP -one could clear the \fIscrollback\fP using -.NS -printf '\\033[\fB3\fPJ' -.NE +one could clear the scrollback buffer as well by using +.RS 8 +.PP +.EX +printf \*'\e033[\fB3\fPJ\*' +.EE +.RE .IP -This is documented in \fIXTerm Control Sequences\fP as a feature originating -with \fBxterm\fP. +instead. +\*(``XTerm Control Sequences\fP\*('' documents this feature as +originating with \fIxterm\fP. .bP -A few other terminal developers adopted the feature, e.g., PuTTY in 2006. +A few other terminal emulators adopted it, +such as 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. +Documentation of this change, +appearing in Linux 3.0, +did not mention \fIxterm\fP, +although that program was cited in the Red Hat bug report (#683733) +motivating the feature. .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. +Subsequently, +more terminal developers adopted the feature. +The next relevant step was to change the \fI\%ncurses\fP \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. +In 2013, +the \fBE3\fP capability was not exercised by +\*(``\fB\%tput clear\fP\*(''. +That oversight was addressed in 2016 by reorganizing \fB\%tput\fP to +share its logic with \fB\%clear\fP and \fB\%tset\fP. .SH SEE ALSO -\fBtput\fP(1), -\fBxterm\fP(1), -\fBterminfo\fP(\*n). -.PP -This describes \fBncurses\fP -version 6.4 (patch 20230520). +\fB\%tput\fP(1), +\fB\%xterm\fP(1), +\fB\%terminfo\fP(5) |