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
 .\"***************************************************************************
 '\" 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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
 .TH @TPUT@ 1 ""
 .ds d @TERMINFO@
 .ds n 1


@@ -133,32 +133,83 @@ occur:
 .RS
 .TP 5
 (1)
 .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)
 .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)
 .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
 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
 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
 .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
 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
 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
 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