Re: CVS commit: src/lib/libcurses

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

On Tue, Jul 27, 2021 at 12:22:18AM +0300, Valery Ushakov wrote:
> I'm not sure what is the discussion you are referring to, but it's not
> a matter of a simple rewording.  "It's complicated", as it ties into a
> few other things, so ideally it needs a coordinated change to several
> man pages.

During aiomixer review, someone complained that it wasn't usable and
mentioned that their terminal only had A_STANDOUT. I was reluctant to
start using A_STANDOUT because of the big warning in the BUGS section
of the man page not to use it, which you mentioned is probably bogus.

I think you told me that A_STANDOUT should be used for semantic
purposes where it makes sense to use.

> The two key points from the spec that the BUGS section tries to warn
> you about is (emphasis mine):
> 
>   A_STANDOUT - Best highlighting mode of the terminal
> 
>   The standend() and wstandend() functions turn off ALL attributes of
>   the current or specified window.
> 
> Roughly speaking "standout" is a kind of higher-level alais and it
> works differently than other attributes (standend).  Mixing it with
> explicit use of other lower-level attributes is not a good idea.

With this in mind, I would also change curses_attributes.3 to
adequately explain what standout is intended to do rather than
just warning against it.

Proposed diff attached.

Index: curses_attributes.3
===================================================================
RCS file: /cvsroot/src/lib/libcurses/curses_attributes.3,v
retrieving revision 1.9
diff -u -r1.9 curses_attributes.3
--- curses_attributes.3	25 Oct 2018 10:36:56 -0000	1.9
+++ curses_attributes.3	27 Jul 2021 07:37:27 -0000
@@ -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.
Index: curses_standout.3
===================================================================
RCS file: /cvsroot/src/lib/libcurses/curses_standout.3,v
retrieving revision 1.8
diff -u -r1.8 curses_standout.3
--- curses_standout.3	26 Jul 2021 20:17:09 -0000	1.8
+++ curses_standout.3	27 Jul 2021 07:37:27 -0000
@@ -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.