[PATCH 08/11] man/curs_beep.3x: Revise.

[G. Branden Robinson]

Content:
* Expand discussion.  Identify relevant terminfo capability names and
  cap-codes.  Explain what determines whether the library regards the
  requested activities as "possible".
* Add "HISTORY" section.
* Add cross reference to terminfo(5).

Style:
* Recast.

Markup:
* Favor man(7) font style macros over *roff font selection escape
  sequences, except for man page cross references (because
  man/make_sed.sh recognizes only certain patterns when rewriting such
  cross references) and terms in the "NAME" section (because the
  generated edit_man.sh script expects font selection escape sequences
  when scraping terms from there to gather names for man page aliases).
* Break input lines after commas.
---
 man/curs_beep.3x | 79 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 63 insertions(+), 16 deletions(-)

diff --git a/man/curs_beep.3x b/man/curs_beep.3x
index 9806f42b3..13bc38be1 100644
--- a/man/curs_beep.3x
+++ b/man/curs_beep.3x
@@ -41,23 +41,70 @@ .SH SYNOPSIS
 \fBint flash(void);
 .fi
 .SH DESCRIPTION
-The \fBbeep\fP and \fBflash\fP routines are used to alert the terminal user.
-The routine \fBbeep\fP sounds an audible alarm on the terminal, if possible;
-otherwise it flashes the screen (visible bell).
-The routine \fBflash\fP
-flashes the screen, and if that is not possible, sounds the alert.
-If neither
-alert is possible, nothing happens.
-Nearly all terminals have an audible alert
-(bell or beep), but only some can flash the screen.
+.B beep
+and
+.B flash
+alert the terminal user:
+the former by sounding the terminal's audible alarm,
+and the latter by visibly attracting user attention.
+Commonly,
+a terminal implements a visual bell by momentarily reversing the
+character foreground and background colors on the entire display;
+even a monochrome device can do this.
+These functions each attempt the other alert type if the one requested
+is unavailable.
+If neither is available,
+.I curses
+performs no action.
+Nearly all terminals have an audible alert mechanism such as a bell or
+piezoelectric buzzer,
+but only some can flash the screen.
 .SH RETURN VALUE
-These routines return \fBOK\fP if they succeed in beeping or flashing,
-\fBERR\fP otherwise.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+In
+.IR \%ncurses ","
+.B beep
+and
+.B flash
+return
+.B OK
+if the terminal type supports the corresponding capability:
+.B bell
+.RB ( bel )
+for
+.B beep
+and
+.B \%flash_screen
+.RB ( flash )
+for
+.BR flash "."
+Otherwise they return
+.BR ERR "."
 .SH EXTENSIONS
-SVr4's beep and flash routines always returned \fBOK\fP, so it was not
-possible to tell when the beep or flash failed.
+In
+.IR \%ncurses ","
+these functions can return
+.BR ERR "."
 .SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
-Like SVr4, it specifies that they always return \fBOK\fP.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+On SVr4
+.IR curses ","
+they always return
+.BR OK ","
+and X/Open Curses specifies them as doing so.
+.SH HISTORY
+.B beep
+and
+.B flash
+appeared in SVr2 (1984).
 .SH SEE ALSO
-\fB\%curses\fP(3X)
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)
-- 
2.30.2

signature.asc
Description: PGP signature