ncurses 6.0 - patch 20170107

[ncurses.git] / man / tput.1

diff --git a/man/tput.1 b/man/tput.1
index 6aafe816534377410ea71711855d4565c9fdd42f..2f42daab516b2e408d0e05f50a2f6e5d438cdc7c 100644 (file)
--- a/man/tput.1
+++ b/man/tput.1
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2012,2016 Free Software Foundation, Inc.              *
+.\" Copyright (c) 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            *
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: tput.1,v 1.46 2016/10/22 19:57:25 tom Exp $
+.\" $Id: tput.1,v 1.50 2017/01/07 23:03:28 tom Exp $
 .TH @TPUT@ 1 ""
 .ds d @TERMINFO@
 .ds n 1
@@ -133,32 +133,83 @@ occur:
 .RS
 .TP 5
 (1)
-if present, the terminal's initialization strings will be
-output as detailed in the \fBterminfo\fR(5) section on
-.IR "Tabs and Initialization" ,
+first, \fB@TPUT@\fR retrieves the current terminal mode settings
+for your terminal.
+It does this by successively testing
+.RS
+.bP
+the standard error,
+.bP
+standard output,
+.bP
+standard input and
+.bP
+ultimately \*(lq/dev/tty\*(rq
+.RE
+.IP
+to obtain terminal settings.
+Having retrieved these settings, \fB@TPUT@\fP remembers which
+file descriptor to use when updating settings.
 .TP
 (2)
-any delays (e.g., newline) specified in the entry will
-be set in the tty driver,
+if the window size cannot be obtained from the operating system,
+but the terminal description (or environment, e.g., \fBLINES\fP
+and \fBCOLUMNS\fP variables specify this),
+update the operating system's notion of the window size.
 .TP
 (3)
+the terminal modes will be updated:
+.RS
+.bP
+any delays (e.g., newline) specified in the entry will
+be set in the tty driver,
+.bP
 tabs expansion will be turned on or off according to
 the specification in the entry, and
-.TP
-(4)
+.bP
 if tabs are not expanded,
 standard tabs will be set (every 8 spaces).
 .RE
+.TP
+(4)
+if present, the terminal's initialization strings will be
+output as detailed in the \fBterminfo\fR(5) section on
+.IR "Tabs and Initialization" ,
+.TP
+(5)
+output is flushed.
+.RE
 .IP
 If an entry does not
 contain the information needed for any of these activities,
 that activity will silently be skipped.
 .TP
 \fBreset\fR
-Instead of putting out initialization strings, the terminal's
-reset strings will be output if present (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
-If the reset strings are not present, but initialization
-strings are, the initialization strings will be output.
+This is similar to \fBinit\fP, with two differences:
+.RS
+.TP 5
+(1)
+before any other initialization,
+the terminal modes will be reset to a \*(``sane\*('' state:
+.RS
+.bP
+set cooked and echo modes,
+.bP
+turn off cbreak and raw modes,
+.bP
+turn on newline translation and
+.bP
+reset any unset special characters to their default values
+.RE
+.TP 5
+(2)
+Instead of putting out \fIinitialization\fP strings, the terminal's
+\fIreset\fP strings will be output if present
+(\fBrs1\fR, \fBrs2\fR, \fBrs3\fR, \fBrf\fR).
+If the \fIreset\fP strings are not present, but \fIinitialization\fP
+strings are, the \fIinitialization\fP strings will be output.
+.RE
+.IP
 Otherwise, \fBreset\fR acts identically to \fBinit\fR.
 .TP
 \fBlongname\fR
@@ -188,6 +239,20 @@ in contrast to the tab-stops and margins which are set by this utility.
 The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
 because of this difference with resetting terminal modes and special characters.
 .PP
+With the changes made for ncurses 6.1, the \fIreset\fP feature of the
+two programs is (mostly) the same.  A few differences remain:
+.bP
+The \fB@TSET@\fP program waits one second when resetting,
+in case it happens to be a hardware terminal.
+.bP
+The two programs write the terminal initialization strings
+to different streams (i.e.,. the standard error for \fB@TSET@\fP and the
+standard output for \fB@TPUT@\fP).
+.IP
+\fBNote:\fP although these programs write to different streams,
+redirecting their output to a file will capture only part of their actions.
+The changes to the terminal modes are not affected by redirecting the output.
+.PP
 If \fB@TPUT@\fR is invoked by a link named \fBinit\fR, this has the
 same effect as \fB@TPUT@ init\fR.
 Again, you are less likely to use that link because another program