[PATCH 35/40] man/curs_border.3x: Revise; add "HISTORY" section.

[G. Branden Robinson]

Content:
* Discuss `wborder` and `border` thoroughly before presenting `box`.
* Document additional failure mode.
* Note non-orthogonality of `box` (there's no `wbox`).
* Extend list of function symbols that may exist as macros.
* Generalize claim about interior (né "inside") borders; this fact was
  true of BSD curses as well.
* In "PORTABILITY" section, document difference in `box` handling of
  corner cells between BSD and System V curses.

Style:
* Protect literals from hyphenation.
* Recast.

Markup:
* Define page-local `bP` macro to set bulleted paragraphs..
* 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 thence to gather names for man page aliases).
---
 man/curs_border.3x | 194 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 147 insertions(+), 47 deletions(-)

diff --git a/man/curs_border.3x b/man/curs_border.3x
index 3732d7c6f..999a39940 100644
--- a/man/curs_border.3x
+++ b/man/curs_border.3x
@@ -39,6 +39,11 @@
 .ie t .ds '' ''
 .el   .ds '' ""
 .\}
+.
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .SH NAME
 \fB\%border\fP,
 \fB\%wborder\fP,
@@ -75,72 +80,111 @@ .SH SYNOPSIS
 \fBint mvwvline(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB, chtype \fIch\fB, 
int \fIn\fB);\fR
 .fi
 .SH DESCRIPTION
-The \fBborder\fP, \fBwborder\fP and \fBbox\fP routines
-draw a box around the edges of a window.
-Other than the window, each argument is a character with attributes:
-.sp
+.B \%wborder
+and
+.B \%border
+draw a box at the edges of the specified window or
+.BR \%stdscr ","
+respectively.
+Each
+.I \%chtype
+argument corresponds to a geometric component of the border as follows:
 .RS
-\fIls\fP \- left side,
+.I ls
+\- left side,
 .br
-\fIrs\fP \- right side,
+.I rs
+\- right side,
 .br
-\fIts\fP \- top side,
+.I ts
+\- top side,
 .br
-\fIbs\fP \- bottom side,
+.I bs
+\- bottom side,
 .br
-\fItl\fP \- top left-hand corner,
+.I tl
+\- top left-hand corner,
 .br
-\fItr\fP \- top right-hand corner,
+.I tr
+\- top right-hand corner,
 .br
-\fIbl\fP \- bottom left-hand corner, and
+.I bl
+\- bottom left-hand corner, and
 .br
-\fIbr\fP \- bottom right-hand corner.
+.I br
+\- bottom right-hand corner.
 .RE
 .PP
-If any of these arguments is zero, then the corresponding
-default values (defined in \fBcurses.h\fP) are used instead:
-.sp
+If any
+.I \%chtype
+argument is
+.BR 0 ","
+then
+.I curses
+uses forms-drawing characters
+(see \fBaddch\fP(3X))
+in the following correspondence:
 .RS
-\fBACS_VLINE\fP,
+.BR \%ACS_VLINE ","
 .br
-\fBACS_VLINE\fP,
+.BR \%ACS_VLINE ","
 .br
-\fBACS_HLINE\fP,
+.BR \%ACS_HLINE ","
 .br
-\fBACS_HLINE\fP,
+.BR \%ACS_HLINE ","
 .br
-\fBACS_ULCORNER\fP,
+.BR \%ACS_ULCORNER ","
 .br
-\fBACS_URCORNER\fP,
+.BR \%ACS_URCORNER ","
 .br
-\fBACS_LLCORNER\fP,
+.BR \%ACS_LLCORNER ","
+and
 .br
-\fBACS_LRCORNER\fP.
+.BR \%ACS_LRCORNER "."
 .RE
 .PP
-\fBbox(\fIwin\fB, \fIverch\fB, \fIhorch\fB)\fR is a shorthand
-for the following call: \fBwborder(\fIwin\fB,\fR \fIverch\fB,\fR
-\fIverch\fB,\fR \fIhorch\fB,\fR \fIhorch\fB, 0, 0, 0, 0)\fR.
+.BI \%box( win ","
+.IB verch ,
+.IB horch )
+is shorthand for
+.RB \%\*(`` wborder(\c
+.IB win ,
+.IB verch ,
+.IB horch ,
+.BR "0, 0, 0, 0)" "\*(''."
 .PP
-The \fBhline\fP and \fBwhline\fP functions draw a horizontal (left to right)
-line using \fIch\fP starting at the current cursor position in the window.
-The
-current cursor position is not changed.
-The line is at most \fIn\fP characters
-long, or as many as fit into the window.
-.PP
-The \fBvline\fP and \fBwvline\fP functions draw a vertical (top to bottom) line
-using \fIch\fP starting at the current cursor position in the window.
-The
-current cursor position is not changed.
-The line is at most \fIn\fP characters
-long, or as many as fit into the window.
+.B \%whline
+draws a horizontal line of
+.I ch
+from left to right,
+and
+.B \%wvline
+a vertical one from top to bottom,
+stopping once
+.I n
+characters have been drawn or upon reaching the boundary of
+.IR win "."
+These functions do not update the cursor position
+(beyond any motion directed by their \*(``mv\*('' variants).
+\fB\%ncurses\fP(3X) describes the variants of these functions.
 .SH RETURN VALUE
-All routines return the integer \fBOK\fP.
-.PP
-This implementation returns
+These functions return
+.B OK
+on success and
 .B ERR
-if the window pointer is null.
+on failure.
+.PP
+In
+.IR \%ncurses ","
+.bP
+these functions fail if the screen is not initialized;
+and
+.bP
+functions taking a
+.I \%WINDOW
+pointer argument fail if
+.I win
+is a null pointer.
 .PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
@@ -148,13 +192,33 @@ .SH RETURN VALUE
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-.B \%border
-and
+Unusually,
+there is no
+.B \%wbox
+function;
 .B \%box
+behaves as one would expect
+.B \%wbox
+to,
+accepting a
+.I \%WINDOW
+pointer argument.
+.PP
+.BR \%border ","
+.BR \%box ","
+.BR \%hline ","
+.BR \%mvhline ","
+.BR \%mvwhline ","
+.BR \%vline ","
+.BR \%mvvline ","
+and
+.B \%mvwvline
 may be implemented as macros.
 .PP
-The borders generated by these functions are \fIinside\fP borders (this
-is also true of SVr4 curses, though the fact is not documented).
+Borders drawn by these functions are
+.I interior
+borders.
+.\" 
https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/libcurses/box.c
 .SH PORTABILITY
 These functions are described in X/Open Curses Issue\ 4.
 It specifies no error conditions for them.
@@ -176,6 +240,42 @@ .SH PORTABILITY
 in
 .IR \%ncurses ","
 it does not.
+.PP
+BSD
+.I curses
+drew boxes with
+.I horch
+in
+.I every
+character cell of the top and bottom lines of the window,
+whereas SVr3.1 and later
+.IR curses ","
+because its
+.I box
+wrapped
+.IR wborder ","
+used the default corner characters.
+.\" https://github.com/ryanwoodsmall/oldsysv/blob/master/sysvr3/31/\
+.\"   usr/src/lib/libcurses/screen/curses.ed#L454
+.SH HISTORY
+4BSD (1980)
+introduced
+.IR box ","
+defining it as a function.
+.PP
+SVr3.1 (1987)
+added
+.I \%whline
+and
+.I \%wvline
+and their variants,
+as well as
+.I \%border
+and
+.IR \%wborder ","
+redefining
+.I \%box
+as a macro wrapping the latter.
 .SH SEE ALSO
 \fB\%curses\fP(3X),
 \fB\%curs_outopts\fP(3X)
-- 
2.30.2

signature.asc
Description: PGP signature