X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_addch.3x;h=cfcb4a267d8a45044fa62e208772c5121f734d24;hp=f0439992247fcf77c7f700449cf0932966837d54;hb=8d3ea9021573747ecd129228ba7782a03243f62c;hpb=58552e8c761a70f8f0bd591fecdf576fa8216e3e

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index f0439992..cfcb4a26 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -27,10 +27,15 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_addch.3x,v 1.38 2017/01/07 19:25:15 tom Exp $
+.\" $Id: curs_addch.3x,v 1.44 2017/11/20 01:27:20 tom Exp $
 .TH curs_addch 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
 \fBaddch\fR,
@@ -58,7 +63,7 @@
 .SS Adding characters
 The \fBaddch\fR, \fBwaddch\fR, \fBmvaddch\fR and \fBmvwaddch\fR routines put
 the character \fIch\fR into the given window at its current window position,
-which is then advanced.  They are analogous to \fBputchar\fR in \fBstdio\fR(3).
+which is then advanced.  They are analogous to \fBputchar\fR(3) in \fBstdio\fR(3).
 If the advance is at the right margin:
 .bP
 The cursor automatically wraps to the beginning of the next line.
@@ -117,50 +122,52 @@ library is unable to use Unicode.
 The names are taken from VT100 nomenclature.
 .PP
 .TS
-l l l
-_ _ _
-l l l.
-\fIName\fR	\fIDefault\fR	\fIDescription\fR
-ACS_BLOCK	#	solid square block
-ACS_BOARD	#	board of squares
-ACS_BTEE	+	bottom tee
-ACS_BULLET	o	bullet
-ACS_CKBOARD	:	checker board (stipple)
-ACS_DARROW	v	arrow pointing down
-ACS_DEGREE	'	degree symbol
-ACS_DIAMOND	+	diamond
-ACS_GEQUAL	>	greater-than-or-equal-to
-ACS_HLINE	\-	horizontal line
-ACS_LANTERN	#	lantern symbol
-ACS_LARROW	<	arrow pointing left
-ACS_LEQUAL	<	less-than-or-equal-to
-ACS_LLCORNER	+	lower left-hand corner
-ACS_LRCORNER	+	lower right-hand corner
-ACS_LTEE	+	left tee
-ACS_NEQUAL	!	not-equal
-ACS_PI	*	greek pi
-ACS_PLMINUS	#	plus/minus
-ACS_PLUS	+	plus
-ACS_RARROW	>	arrow pointing right
-ACS_RTEE	+	right tee
-ACS_S1	\-	scan line 1
-ACS_S3	\-	scan line 3
-ACS_S7	\-	scan line 7
-ACS_S9	\&_	scan line 9
-ACS_STERLING	f	pound-sterling symbol
-ACS_TTEE	+	top tee
-ACS_UARROW	^	arrow pointing up
-ACS_ULCORNER	+	upper left-hand corner
-ACS_URCORNER	+	upper right-hand corner
-ACS_VLINE	|	vertical line
+l l l l
+l l l l
+_ _ _ _
+l l l l.
+\fBACS\fR	\fBACS\fR	\fBacsc\fP	\fBGlyph\fR
+\fBName\fR	\fBDefault\fR	\fBchar\fP	\fBName\fR
+ACS_BLOCK	#	0	solid square block
+ACS_BOARD	#	h	board of squares
+ACS_BTEE	+	v	bottom tee
+ACS_BULLET	o	~	bullet
+ACS_CKBOARD	:	a	checker board (stipple)
+ACS_DARROW	v	.	arrow pointing down
+ACS_DEGREE	'	f	degree symbol
+ACS_DIAMOND	+	`	diamond
+ACS_GEQUAL	>	>	greater-than-or-equal-to
+ACS_HLINE	\-	q	horizontal line
+ACS_LANTERN	#	i	lantern symbol
+ACS_LARROW	<	,	arrow pointing left
+ACS_LEQUAL	<	y	less-than-or-equal-to
+ACS_LLCORNER	+	m	lower left-hand corner
+ACS_LRCORNER	+	j	lower right-hand corner
+ACS_LTEE	+	t	left tee
+ACS_NEQUAL	!	|	not-equal
+ACS_PI	*	{	greek pi
+ACS_PLMINUS	#	g	plus/minus
+ACS_PLUS	+	n	plus
+ACS_RARROW	>	+	arrow pointing right
+ACS_RTEE	+	u	right tee
+ACS_S1	\-	o	scan line 1
+ACS_S3	\-	p	scan line 3
+ACS_S7	\-	r	scan line 7
+ACS_S9	\&_	s	scan line 9
+ACS_STERLING	f	}	pound-sterling symbol
+ACS_TTEE	+	w	top tee
+ACS_UARROW	^	\-	arrow pointing up
+ACS_ULCORNER	+	l	upper left-hand corner
+ACS_URCORNER	+	k	upper right-hand corner
+ACS_VLINE	|	x	vertical line
 .TE
 .SH RETURN VALUE
 All routines return the integer \fBERR\fR upon failure and \fBOK\fR on success
-(the SVr4 manuals specify only "an integer value other than \fBERR\fR") upon
-successful completion, unless otherwise noted in the preceding routine
-descriptions.
+(the SVr4 manuals specify only
+\*(``an integer value other than \fBERR\fR\*('') upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
 .PP
-Functions with a "mv" prefix first perform a cursor movement using
+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.
 .SH NOTES
@@ -169,6 +176,7 @@ Note that \fBaddch\fR, \fBmvaddch\fR, \fBmvwaddch\fR, and
 .SH PORTABILITY
 All these functions are described in the XSI Curses standard, Issue 4.
 The defaults specified for forms-drawing characters apply in the POSIX locale.
+.SS ACS Symbols
 .LP
 X/Open Curses states that the \fIACS_\fP definitions are \fBchar\fP constants.
 For the wide-character implementation (see \fBcurs_add_wch\fP),
@@ -199,6 +207,44 @@ whether the \fIlocale\fP uses UTF-8 encoding.
 In certain cases, the terminal is unable to display line-drawing characters
 except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in
 ncurses(3X)).
+.SS Character Set
+X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
+a single character.
+As discussed in \fBcurs_attr\fP(3X), that character may have been
+more than eight bits in an SVr3 or SVr4 implementation,
+but in the X/Open Curses model, the details are not given.
+The important distinction between SVr4 curses and X/Open Curses is
+that the non-character information (attributes and color) was
+separated from the character information which is packed in a \fBchtype\fP
+to pass to \fBwaddch\fP.
+.PP
+In this implementation, \fBchtype\fP holds eight bits.
+But ncurses allows multibyte characters to be passed in a succession
+of calls to \fBwaddch\fP.
+The other implementations do not do this;
+a call to \fBwaddch\fP passes exactly one character
+which may be rendered as one or more cells on the screen
+depending on whether it is printable.
+.PP
+Depending on the locale settings,
+ncurses will inspect the byte passed in each call to \fBwaddch\fP,
+and check if the latest call will continue a multibyte sequence.
+When a character is \fIcomplete\fP,
+ncurses displays the character and moves to the next position in the screen.
+.PP
+If the calling application interrupts the succession of bytes in
+a multibyte character by moving the current location (e.g., using \fBwmove\fP),
+ncurses discards the partially built character,
+starting over again.
+.PP
+For portability to other implementations,
+do not rely upon this behavior:
+.bP
+check if a character can be represented as a single byte in the current locale
+before attempting call \fBwaddch\fP, and
+.bP
+call \fBwadd_wch\fP for characters which cannot be handled by \fBwaddch\fP.
+.SS TABSIZE
 .LP
 The \fBTABSIZE\fR variable is implemented in some versions of curses,
 but is not part of X/Open curses.