[src/trunk]: src/lib/libcurses curses: clarify documentation regarding the st...

[nia <nia%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7835820347cf
branches:  trunk
changeset: 1022699:7835820347cf
user:      nia <nia%NetBSD.org@localhost>
date:      Mon Aug 02 11:11:20 2021 +0000

description:
curses: clarify documentation regarding the standout attribute

diffstat:

 lib/libcurses/curses_attributes.3 |  13 ++++++++-----
 lib/libcurses/curses_standout.3   |  13 +++++++++++--
 2 files changed, 19 insertions(+), 7 deletions(-)

diffs (86 lines):

diff -r 9a3a3938ca6c -r 7835820347cf lib/libcurses/curses_attributes.3
--- a/lib/libcurses/curses_attributes.3 Sun Aug 01 21:58:56 2021 +0000
+++ b/lib/libcurses/curses_attributes.3 Mon Aug 02 11:11:20 2021 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: curses_attributes.3,v 1.9 2018/10/25 10:36:56 uwe Exp $
+.\"    $NetBSD: curses_attributes.3,v 1.10 2021/08/02 11:11:20 nia Exp $
 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
@@ -25,7 +25,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 25, 2018
+.Dd July 27, 2021
 .Dt CURSES_ATTRIBUTES 3
 .Os
 .Sh NAME
@@ -102,7 +102,7 @@
 .It A_NORMAL
 no special attributes are applied
 .It A_STANDOUT
-characters are displayed in standout mode
+characters are displayed in the "best" highlighting mode of the terminal
 .It A_UNDERLINE
 characters are displayed underlined
 .It A_REVERSE
@@ -193,7 +193,7 @@
 .Pp
 .Bl -tag -width "COLOR_PAIR(n)" -compact -offset indent
 .It WA_STANDOUT
-characters are displayed in standout mode
+characters are displayed in the "best" highlighting mode of the terminal
 .It WA_UNDERLINE
 characters are displayed underlined
 .It WA_REVERSE
@@ -336,7 +336,10 @@
 .Sh HISTORY
 These functions first appeared in
 .Nx 1.5 .
-.Sh BUGS
+.Sh CAVEATS
 Some terminals do not support characters with both color and other attributes
 set.
 In this case, the other attribute is displayed instead of the color attribute.
+.Pp
+The standout attribute is a higher level alias and should not be mixed with
+other attributes.
diff -r 9a3a3938ca6c -r 7835820347cf lib/libcurses/curses_standout.3
--- a/lib/libcurses/curses_standout.3   Sun Aug 01 21:58:56 2021 +0000
+++ b/lib/libcurses/curses_standout.3   Mon Aug 02 11:11:20 2021 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: curses_standout.3,v 1.8 2021/07/26 20:17:09 nia Exp $
+.\"    $NetBSD: curses_standout.3,v 1.9 2021/08/02 11:11:20 nia Exp $
 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
@@ -25,7 +25,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 26, 2021
+.Dd July 27, 2021
 .Dt CURSES_STANDOUT 3
 .Os
 .Sh NAME
@@ -55,6 +55,9 @@
 These functions manipulate the standout attribute on
 .Dv stdscr
 or on the specified window.
+The standout attribute applies the "best highlighting mode"
+supported by the current terminal, which may be an alias of
+other attributes.
 .Pp
 The
 .Fn standout
@@ -101,3 +104,9 @@
 .Sh HISTORY
 The Curses package appeared in
 .Bx 4.0 .
+.Sh CAVEATS
+On some terminals, characters with standout set may have the same appearance
+as characters with the reverse video or bold attribute set.
+However, on legacy terminals, standout may be the only attribute that can be
+used to emphasize characters.
+The standout attribute should not be mixed with other attributes.