X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_addch.3x;fp=man%2Fcurs_addch.3x;h=cfa7bf121277feaf2792d9e517b01ac8a2cbf496;hb=fc11bff62abb32a3e7724180a94c1068c148ea6c;hp=ad548520ce84c792df349b76f9ab294533b88e6a;hpb=e607aef87171fae9359b0c43a04d8d932719bc71;p=ncurses.git

diff --git a/man/curs_addch.3x b/man/curs_addch.3x
index ad548520..cfa7bf12 100644
--- a/man/curs_addch.3x
+++ b/man/curs_addch.3x
@@ -28,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp $
-.TH curs_addch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_addch.3x,v 1.86 2024/05/11 20:39:53 tom Exp $
+.TH curs_addch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -72,22 +72,24 @@ add a \fIcurses\fP character to a window and advance the cursor
 \fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
 .fi
 .SH DESCRIPTION
-.SS "Adding Characters"
+.SS waddch
 .B \%waddch
-puts the character
+writes the
+.I curses
+character
 .I ch
-at the cursor position of window
-.IR win ,
+to the window
+.IR win ","
 then advances the cursor position,
 analogously to the standard C library's \fI\%putchar\fP(3).
 \fB\%ncurses\fP(3X) describes the variants of this function.
 .PP
 If advancement occurs at the right margin,
 .bP
-the cursor automatically wraps to the beginning of the next line;
-and
+the cursor automatically wraps to the beginning of the next line,
+then,
 .bP
-at the bottom of the current scrolling region,
+if it was at the bottom of the scrolling region,
 and if \fB\%scrollok\fP(3X) is enabled for
 .IR win ,
 the scrolling region scrolls up one line.
@@ -110,10 +112,7 @@ Carriage return moves the cursor to the left margin on the current line
 of the window.
 .bP
 Line feed does a \fB\%clrtoeol\fP(3X),
-then moves the cursor to the left margin on the next line of the window,
-and if \fB\%scrollok\fP(3X) is enabled for
-.IR win ,
-scrolls the window if the cursor was already on the last line.
+then advances as if from the right margin.
 .bP
 Tab advances the cursor to the next tab stop
 (possibly on the next line);
@@ -126,23 +125,22 @@ see \fB\%curs_variables\fP(3X).
 If
 .I ch
 is any other nonprintable character,
-it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X).
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
 .PP
 Calling \fB\%winch\fP(3X) on the location of a nonprintable character
 does not return the character itself,
 but its \fB\%unctrl\fP(3X) representation.
 .PP
+The object or expression
 .I ch
-may contain rendering and/or color attributes,
-and others can be combined with the parameter
-by logically \*(``or\*(''ing with it.
+may contain attributes and/or a color pair identifier.
 (A character with its attributes can be copied from place to place
 using \fB\%winch\fP(3X) and
 .BR \%waddch .)
 See \fB\%curs_attr\fP(3X) for values of predefined video attribute
 constants that can be usefully \*(``or\*(''ed with characters.
-.SS "Echoing Characters"
+.SS wechochar
 .B \%echochar
 and
 .B \%wechochar
@@ -177,8 +175,9 @@ these characters but the library is unable to use Unicode.
 The \*(``acsc char\*('' column corresponds to how the characters are
 specified in the
 .B \%acs_chars
+.RB ( \%acsc )
 string capability,
-and the characters in it may appear on the screen if the terminal's
+and the characters in it may appear on the screen if the terminal type's
 database entry incorrectly advertises ACS support.
 The name \*(``ACS\*('' originates in the Alternate Character Set feature
 of the DEC VT100 terminal.
@@ -235,36 +234,52 @@ In
 .B \%waddch
 returns
 .B ERR
-if it is not possible to add a complete character at the cursor
-position,
-as when conversion of a multibyte character to a byte sequence fails,
-or at least one of the resulting bytes cannot be added to the window.
+if
+.bP
+.I win
+is
+.BR NULL ","
+.bP
+wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
+not been called on
+.I win
+when a write to its bottom right location is attempted,
+or
+.bP
+it is not possible to add a complete character at the cursor position.
+.PP
+The last may be due to different causes:
+.bP
+conversion of a multibyte character to a byte sequence can fail,
+or
+.bP
+at least one of the bytes resulting from conversion from a multibyte
+sequence cannot be added to the window.
 See section \*(``PORTABILITY\*('' below regarding the use of
 .B \%waddch
 with multibyte characters.
 .PP
-.B \%waddch
-can successfully write a character at the bottom right location of the
-window.
-However,
-.I \%ncurses
-returns
-.B ERR
-if \fB\%scrollok\fP(3X) is not enabled in that event,
-because it is not possible to wrap to a new line.
-.PP
 Functions prefixed with \*(``mv\*('' first perform cursor movement and
 fail if the position
 .RI ( y ,
 .IR x )
 is outside the window boundaries.
 .SH NOTES
-.BR \%addch ,
-.BR \%mvaddch ,
-.BR \%mvwaddch ,
+.BR \%addch ","
+.BR \%mvaddch ","
+.BR \%mvwaddch ","
 and
 .B \%echochar
 may be implemented as macros.
+.SH EXTENSIONS
+.SS TABSIZE
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it;
+see \fB\%curs_variables\fP(3X).
 .SH PORTABILITY
 X/Open Curses,
 Issue 4 describes these functions.
@@ -290,7 +305,7 @@ Some implementations are problematic.
 Solaris
 .IR curses ,
 for example,
-define the ACS symbols as constants;
+defines the ACS symbols as constants;
 others define them as elements of an array.
 .IP
 This implementation uses an array,
@@ -356,8 +371,8 @@ many publicly available
 .I \%term\%info
 entries include
 .B \%acsc
-strings in which their key characters
-.BR ( pryz{|} )
+capabilities in which their key characters
+.RB ( pryz{|} )
 are embedded,
 and a second-hand list of their character descriptions has come to
 light.
@@ -386,51 +401,50 @@ the terminal is unable to display forms-drawing characters
 by using UTF-8;
 see the discussion of the
 .I \%NCURSES_NO_UTF8_ACS
-environment variable in \fB\%ncurses\fP(3X)).
+environment variable in \fB\%ncurses\fP(3X).
 .SS "Character Set"
 X/Open Curses assumes that the parameter passed to
 .B \%waddch
 contains a single character.
-As discussed in \fB\%curs_attr\fP(3X),
-that character may have been more than eight bits wide in an SVr3 or
+That character may have been more than eight bits wide in an SVr3 or
 SVr4 implementation,
-but in the X/Open Curses model,
-the details are not given.
-The important distinction between SVr4
-.I curses
-and X/Open Curses is that the latter separates non-character information
-(attributes and color)
-from the character code,
-which SVr4 packs into a
+but X/Open Curses leaves the width of a non-wide character code
+unspecified.
+The standard further does not specify the internal structure of a
+.IR chtype ","
+though the use of bit operations to combine the character code with
+attributes and a color pair identifier into a
 .I \%chtype
 for passage to
-.BR \%waddch .
+.B \%waddch
+is common.
+A portable application uses only the macros discussed in
+\fB\%curs_attr\fP(3X) to manipulate a
+.IR \%chtype "."
 .PP
 In
 .IR \%ncurses ,
 .I \%chtype
-holds an eight-bit character.
-But the library allows a multibyte character to be passed in a
+holds an eight-bit character,
+but the library allows a multibyte character to be passed in a
 succession of calls to
-.BR \%waddch .
+.BR \%waddch "."
 Other implementations do not;
 a
 .B \%waddch
 call transmits exactly one character,
 which may be rendered in one or more screen locations depending on
-whether it is printable.
-.PP
-Depending on the locale settings,
+whether it is printable
+(see \fB\%unctrl\fP(3X)).
+Depending on the locale,
 .I \%ncurses
 inspects the byte passed in each
 .B \%waddch
-call,
-and checks whether the latest call continues a multibyte sequence.
+call and checks whether the latest call continues a multibyte sequence.
 When a character is
-.IR complete ,
+.IR complete ","
 .I \%ncurses
 displays the character and advances the cursor.
-.PP
 If the calling application interrupts the succession of bytes in
 a multibyte character sequence by changing the current location\(emfor
 example,
@@ -439,7 +453,7 @@ with \fB\%wmove\fP(3X)\(em\c
 discards the incomplete character.
 .PP
 For portability to other implementations,
-do not rely upon this behavior.
+do not rely upon the foregoing behavior.
 Check whether a character can be represented as a single byte in the
 current locale.
 .bP
@@ -451,14 +465,6 @@ or \fB\%wadd_wch\fP(3X).
 If it cannot,
 use only
 \fB\%wadd_wch\fP(3X).
-.SS TABSIZE
-SVr4 and other versions of
-.I curses
-implement the
-.B \%TABSIZE
-variable,
-but X/Open Curses does not specify it
-(see \fB\%curs_variables\fP(3X)).
 .SH SEE ALSO
 \fB\%curs_add_wch\fP(3X) describes comparable functions of the
 .I \%ncurses