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.