ncurses 6.2 - patch 20201017

[ncurses.git] / man / curs_add_wch.3x

diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
index b5397eb7fda04fd1eeee36f69e20c94aa67eab2d..446020839cd19e614ef6f3e9c75b87a5301beb86 100644 (file)
--- a/man/curs_add_wch.3x
+++ b/man/curs_add_wch.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 2001-2015,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2019,2020 Thomas E. Dickey                                     *
+.\" Copyright 2001-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
@@ -26,14 +27,15 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_add_wch.3x,v 1.22 2017/05/06 14:01:26 tom Exp $
+.\" $Id: curs_add_wch.3x,v 1.28 2020/10/17 23:10:38 tom Exp $
 .TH curs_add_wch 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
 .el       .ds '' ''
 .de bP
-.IP \(bu 4
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
 ..
 .SH NAME
 \fBadd_wch\fP,
@@ -53,7 +55,7 @@
 .B "int mvadd_wch( int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
 .br
 .B "int mvwadd_wch( WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwch\fB );"
-.br
+.sp
 .B "int echo_wchar( const cchar_t *\fIwch\fB );"
 .br
 .B "int wecho_wchar( WINDOW *\fIwin\fP, const cchar_t *\fIwch\fB );"
@@ -154,7 +156,28 @@ WACS_VLINE 0x2502  |       x       vertical line
 .TE
 .PP
 The wide-character configuration of ncurses also defines symbols
-for double-lines:
+for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
+.TS
+l l l l l
+l l l l l
+_ _ _ _ _
+lw(1.5i) lw5 lw5 lw5 lw20.
+\fBACS\fR      \fBUnicode\fP   \fBASCII\fR     \fBacsc\fP      \fBGlyph\fR
+\fBName\fR     \fBDefault\fP   \fBDefault\fR   \fBchar\fP      \fBName\fR
+WACS_T_BTEE    0x253b  +       V       thick tee pointing up
+WACS_T_HLINE   0x2501  -       Q       thick horizontal line
+WACS_T_LLCORNER        0x2517  +       M       thick lower left corner
+WACS_T_LRCORNER        0x251b  +       J       thick lower right corner
+WACS_T_LTEE    0x252b  +       T       thick tee pointing right
+WACS_T_PLUS    0x254b  +       N       thick large plus
+WACS_T_RTEE    0x2523  +       U       thick tee pointing left
+WACS_T_TTEE    0x2533  +       W       thick tee pointing down
+WACS_T_ULCORNER        0x250f  +       L       thick upper left corner
+WACS_T_URCORNER        0x2513  +       K       thick upper right corner
+WACS_T_VLINE   0x2503  |       X       thick vertical line
+.TE
+.PP
+and for double-lines (\fBacsc\fP \*(``A\*('' to \*(``I\*(''):
 .PP
 .TS
 l l l l l
@@ -176,30 +199,38 @@ WACS_D_URCORNER   0x2557  +       B       double upper right corner
 WACS_D_VLINE   0x2551  |       Y       double vertical line
 .TE
 .PP
-and for thick lines:
-.TS
-l l l l l
-l l l l l
-_ _ _ _ _
-lw(1.5i) lw5 lw5 lw5 lw20.
-\fBACS\fR      \fBUnicode\fP   \fBASCII\fR     \fBacsc\fP      \fBGlyph\fR
-\fBName\fR     \fBDefault\fP   \fBDefault\fR   \fBchar\fP      \fBName\fR
-WACS_T_BTEE    0x253b  +       V       thick tee pointing up
-WACS_T_HLINE   0x2501  -       Q       thick horizontal line
-WACS_T_LLCORNER        0x2517  +       M       thick lower left corner
-WACS_T_LRCORNER        0x251b  +       J       thick lower right corner
-WACS_T_LTEE    0x252b  +       T       thick tee pointing right
-WACS_T_PLUS    0x254b  +       N       thick large plus
-WACS_T_RTEE    0x2523  +       U       thick tee pointing left
-WACS_T_TTEE    0x2533  +       W       thick tee pointing down
-WACS_T_ULCORNER        0x250f  +       L       thick upper left corner
-WACS_T_URCORNER        0x2513  +       K       thick upper right corner
-WACS_T_VLINE   0x2503  |       X       thick vertical line
-.TE
+Unicode's descriptions for these characters differs slightly from ncurses,
+by introducing the term \*(``light\*('' (along with less important details).
+Here are its descriptions for the normal, thick, and double horizontal lines:
+.bP
+U+2500 BOX DRAWINGS LIGHT HORIZONTAL
+.bP
+U+2501 BOX DRAWINGS HEAVY HORIZONTAL
+.bP
+U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
 .SH RETURN VALUE
 .PP
 All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success.
 .PP
+X/Open does not define any error conditions.
+This implementation returns an error
+.bP
+if the window pointer is null or
+.bP
+if it is not possible to add a complete character in the window.
+.PP
+The latter may be due to different causes:
+.bP
+If \fBscrollok\fR is not enabled,
+writing a character at the lower right margin succeeds.
+However, an error is returned because
+it is not possible to wrap to a new line
+.bP
+If an error is detected when converting a multibyte character to a sequence
+of bytes,
+or if it is not possible to add all of the resulting bytes in the window,
+an error is returned.
+.PP
 Functions with a \*(``mv\*('' prefix first perform a cursor movement using
 \fBwmove\fP, and return an error if the position is outside the window,
 or if the window pointer is null.
@@ -270,7 +301,7 @@ was intended.
 But there are several possibilities, all with problems.
 .IP
 Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and U+1F3EE.
-Those were not availble in 2002, and are irrelevant since
+Those were not available in 2002, and are irrelevant since
 they lie outside the BMP and as a result are not generally available
 in terminals.
 They are not storm lanterns, in any case.