X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=02defb6a793c58f1de8cd966e030fe21678d7c64;hp=9df4c9a9632b0a70e9a9c53205ff6a2c40bf0c68;hb=42259b594b5dabd37fe2bc294051d2db82e873a2;hpb=96d6b16de0d487e5d3aed0302a179dbce11b5d96;ds=sidebyside

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 9df4c9a9..02defb6a 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,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,197 +27,444 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_color.3x,v 1.34 2010/12/04 18:36:44 tom Exp $
+.\" $Id: curs_color.3x,v 1.63 2020/10/24 09:35:23 tom Exp $
 .TH curs_color 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
 ..
+.ds n 5
 .na
 .hy 0
 .SH NAME
 \fBstart_color\fR,
-\fBinit_pair\fR,
-\fBinit_color\fR,
 \fBhas_colors\fR,
 \fBcan_change_color\fR,
+\fBinit_pair\fR,
+\fBinit_color\fR,
+\fBinit_extended_pair\fR,
+\fBinit_extended_color\fR,
 \fBcolor_content\fR,
 \fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
+\fBextended_color_content\fR,
+\fBextended_pair_content\fR,
+\fBreset_color_pairs\fR,
+\fBCOLOR_PAIR\fR,
+\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
 .ad
 .hy
 .SH SYNOPSIS
-\fB# include <curses.h>\fR
+\fB#include <curses.h>\fR
 .sp
 \fBint start_color(void);\fR
+.sp
+\fBbool has_colors(void);\fR
 .br
-\fBint init_pair(short pair, short f, short b);\fR
+\fBbool can_change_color(void);\fR
+.sp
+\fBint init_pair(short \fP\fIpair\fP\fB, short \fP\fIf\fP\fB, short \fP\fIb\fP\fB);\fR
 .br
-\fBint init_color(short color, short r, short g, short b);\fR
+\fBint init_color(short \fP\fIcolor\fP\fB, short \fP\fIr\fP\fB, short \fP\fIg\fP\fB, short \fP\fIb\fP\fB);\fR
 .br
-\fBbool has_colors(void);\fR
+/* extensions */
 .br
-\fBbool can_change_color(void);\fR
+\fBint init_extended_pair(int \fP\fIpair\fP\fB, int \fP\fIf\fP\fB, int \fP\fIb\fP\fB);\fR
+.br
+\fBint init_extended_color(int \fP\fIcolor\fP\fB, int \fP\fIr\fP\fB, int \fP\fIg\fP\fB, int \fP\fIb\fP\fB);\fR
+.sp
+\fBint color_content(short \fP\fIcolor\fP\fB, short *\fP\fIr\fP\fB, short *\fP\fIg\fP\fB, short *\fP\fIb\fP\fB);\fR
 .br
-\fBint color_content(short color, short *r, short *g, short *b);\fR
+\fBint pair_content(short \fP\fIpair\fP\fB, short *\fP\fIf\fP\fB, short *\fP\fIb\fP\fB);\fR
 .br
-\fBint pair_content(short pair, short *f, short *b);\fR
+/* extensions */
+.br
+\fBint extended_color_content(int \fP\fIcolor\fP\fB, int *\fP\fIr\fP\fB, int *\fP\fIg\fP\fB, int *\fP\fIb\fP\fB);\fR
+.br
+\fBint extended_pair_content(int \fP\fIpair\fP\fB, int *\fP\fIf\fP\fB, int *\fP\fIb\fP\fB);\fR
+.sp
+/* extensions */
+.br
+\fBvoid reset_color_pairs(void);\fR
+.sp
+\fBint COLOR_PAIR(int \fP\fIn\fP\fB);\fR
+.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
 .br
 .SH DESCRIPTION
 .SS Overview
-\fBcurses\fR support color attributes on terminals with that capability.  To
-use these routines \fBstart_color\fR must be called, usually right after
-\fBinitscr\fR.  Colors are always used in pairs (referred to as color-pairs).
+\fBcurses\fR supports color attributes on terminals with that capability.
+To use these routines \fBstart_color\fR must be called, usually right after
+\fBinitscr\fR.
+Colors are always used in pairs (referred to as color-pairs).
 A color-pair consists of a foreground color (for characters) and a background
-color (for the blank field on which the characters are displayed).  A
-programmer initializes a color-pair with the routine \fBinit_pair\fR.  After it
-has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in
-\fB<curses.h>\fR, can be used as a new video attribute.
+color (for the blank field on which the characters are displayed).
+A programmer initializes a color-pair with the routine \fBinit_pair\fR.
+After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR)
+can be used to convert the pair to a video attribute.
 .PP
 If a terminal is capable of redefining colors, the programmer can use the
-routine \fBinit_color\fR to change the definition of a color.  The routines
-\fBhas_colors\fR and \fBcan_change_color\fR return \fBTRUE\fR or \fBFALSE\fR,
+routine \fBinit_color\fR to change the definition of a color.
+The routines \fBhas_colors\fR and \fBcan_change_color\fR
+return \fBTRUE\fR or \fBFALSE\fR,
 depending on whether the terminal has color capabilities and whether the
-programmer can change the colors.  The routine \fBcolor_content\fR allows a
+programmer can change the colors.
+The routine \fBcolor_content\fR allows a
 programmer to extract the amounts of red, green, and blue components in an
-initialized color.  The routine \fBpair_content\fR allows a programmer to find
+initialized color.
+The routine \fBpair_content\fR allows a programmer to find
 out how a given color-pair is currently defined.
-.SS Routine Descriptions
-The \fBstart_color\fR routine requires no arguments.  It must be
-called if the programmer wants to use colors, and before any other
-color manipulation routine is called.  It is good practice to call
-this routine right after \fBinitscr\fR.  \fBstart_color\fR initializes
-eight basic colors (black, red, green, yellow, blue, magenta, cyan,
-and white), and two global variables, \fBCOLORS\fR and
+.SS Color Rendering
+The \fBcurses\fP library combines these inputs to produce the
+actual foreground and background colors shown on the screen:
+.bP
+per-character video attributes (e.g., via \fBwaddch\fP),
+.bP
+the window attribute (e.g., by \fBwattrset\fP), and
+.bP
+the background character (e.g., \fBwbkgdset\fP).
+.PP
+Per-character and window attributes are usually set by a parameter containing
+video attributes including a color pair value.
+Some functions such as \fBwattr_set\fP use a separate parameter which
+is the color pair number.
+.PP
+The background character is a special case: it includes a character value,
+just as if it were passed to \fBwaddch\fP.
+.PP
+The \fBcurses\fP library does the actual work of combining these color
+pairs in an internal function called from \fBwaddch\fP:
+.bP
+If the parameter passed to \fBwaddch\fP is \fIblank\fP,
+and it uses the special color pair 0,
+.RS
+.bP
+\fBcurses\fP next checks the window attribute.
+.bP
+If the window attribute does not use color pair 0,
+\fBcurses\fP uses the color pair from the window attribute.
+.bP
+Otherwise, \fBcurses\fP uses the background character.
+.RE
+.bP
+If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
+or it does not use the special color pair 0,
+\fBcurses\fP prefers the color pair from the parameter,
+if it is nonzero.
+Otherwise, it tries the window attribute next, and finally the
+background character.
+.PP
+Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP.
+Those do not combine its parameter with a color pair.
+Consequently those calls use only the window attribute or
+the background character.
+.SH CONSTANTS
+.PP
+In \fB<curses.h>\fR the following macros are defined.
+These are the standard colors (ISO-6429).
+\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
+background color for all terminals.
+.PP
+.nf
+      \fBCOLOR_BLACK\fR
+      \fBCOLOR_RED\fR
+      \fBCOLOR_GREEN\fR
+      \fBCOLOR_YELLOW\fR
+      \fBCOLOR_BLUE\fR
+      \fBCOLOR_MAGENTA\fR
+      \fBCOLOR_CYAN\fR
+      \fBCOLOR_WHITE\fR
+.fi
+.PP
+Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
+There are no standard names for those additional colors.
+.SH VARIABLES
+.SS COLORS
+is initialized by \fBstart_color\fP to the maximum number of colors
+the terminal can support.
+.SS COLOR_PAIRS
+is initialized by \fBstart_color\fP to the maximum number of color pairs
+the terminal can support.
+.SH FUNCTIONS
+.SS start_color
+The \fBstart_color\fR routine requires no arguments.
+It must be called if the programmer wants to use colors, and before any other
+color manipulation routine is called.
+It is good practice to call this routine right after \fBinitscr\fR.
+\fBstart_color\fR does this:
+.bP
+It initializes two global variables, \fBCOLORS\fR and
 \fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
-and color-pairs the terminal can support).  It also restores the
-colors on the terminal to the values they had when the terminal was
-just turned on.
+and color-pairs the terminal can support).
+.bP
+It initializes the special color pair \fB0\fP to the default foreground
+and background colors.
+No other color pairs are initialized.
+.bP
+It restores the colors on the terminal to the values
+they had when the terminal was just turned on.
+.bP
+If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
+\fBstart_color\fP
+initializes its internal table representing the
+red, green, and blue components of the color palette.
+.IP
+The components depend on whether the terminal uses
+CGA (aka \*(``ANSI\*('') or
+HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set).
+The table is initialized first for eight basic colors
+(black, red, green, yellow, blue, magenta, cyan, and white),
+using weights that depend upon the CGA/HLS choice.
+For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
+depending on whether the corresponding
+red, green, or blue component is used or not.
+That permits using \fB1000\fP to represent bold/bright colors.
+After the initial eight colors
+(if the terminal supports more than eight colors)
+the components are initialized using the same pattern,
+but with weights of \fB1000\fP.
+SVr4 uses a similar scheme, but uses \fB1000\fP
+for the components of the initial eight colors.
+.IP
+\fBstart_color\fP does not attempt to set the terminal's color palette
+to match its built-in table.
+An application may use \fBinit_color\fP to alter the internal table
+along with the terminal's color.
 .PP
-The \fBinit_pair\fR routine changes the definition of a color-pair.  It takes
-three arguments: the number of the color-pair to be changed, the foreground
+These limits apply to color values and color pairs.
+Values outside these limits are not legal, and may result in a runtime error:
+.bP
+\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fR capability,
+(see \fBterminfo\fR(\*n)).
+.bP
+color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
+inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
+.bP
+a special color value \fB\-1\fP is used in certain extended functions
+to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3X)).
+.bP
+\fBCOLOR_PAIRS\fP corresponds to
+the terminal database's \fBmax_pairs\fP capability,
+(see \fBterminfo\fR(\*n)).
+.bP
+legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
+inclusive.
+.bP
+color pair \fB0\fP is special; it denotes \*(``no color\*(''.
+.IP
+Color pair \fB0\fP is assumed to be white on black,
+but is actually whatever the terminal implements before color is initialized.
+It cannot be modified by the application.
+.SS has_colors
+.PP
+The \fBhas_colors\fR routine requires no arguments.
+It returns \fBTRUE\fR if
+the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.
+This routine facilitates writing terminal-independent programs.
+For example, a programmer can use it to decide
+whether to use color or some other video attribute.
+.SS can_change_color
+.PP
+The \fBcan_change_color\fR routine requires no arguments.
+It returns \fBTRUE\fR if the terminal supports colors
+and can change their definitions;
+other, it returns \fBFALSE\fR.
+This routine facilitates writing terminal-independent programs.
+.SS init_pair
+.PP
+The \fBinit_pair\fR routine changes the definition of a color-pair.
+It takes three arguments:
+the number of the color-pair to be changed, the foreground
 color number, and the background color number.
 For portable applications:
 .bP
-The value of the first argument
-must be between \fB1\fR and \fBCOLOR_PAIRS\-1\fR,
-except that if default colors are used (see \fBuse_default_colors\fP)
+The first argument must be a legal color pair value.
+If default colors are used (see \fBuse_default_colors\fP(3X))
 the upper limit is adjusted to allow for extra pairs which use
 a default color in foreground and/or background.
 .bP
-The value of the second and
-third arguments must be between 0 and \fBCOLORS\fR.
-Color pair 0 is assumed to be white on black,
-but is actually whatever the terminal implements before color is initialized.
-It cannot be modified by the application.
+The second and third arguments must be legal color values.
 .PP
-If the color-pair was previously
-initialized, the screen is refreshed and all occurrences of that color-pair
+If the color-pair was previously initialized,
+the screen is refreshed and all occurrences of that color-pair
 are changed to the new definition.
 .PP
-As an extension, ncurses allows you to set color pair 0 via
-the \fBassume_default_colors\fR routine, or to specify the use of
+As an extension, ncurses allows you to set color pair \fB0\fP via
+the \fBassume_default_colors\fR(3X) routine, or to specify the use of
 default colors (color number \fB\-1\fR) if you first invoke the
-\fBuse_default_colors\fR routine.
-.PP
-The \fBinit_color\fR routine changes the definition of a color.  It takes four
-arguments: the number of the color to be changed followed by three RGB values
-(for the amounts of red, green, and blue components).  The value of the first
-argument must be between \fB0\fR and \fBCOLORS\fR.  (See the section
-\fBColors\fR for the default color index.)  Each of the last three arguments
-must be a value between 0 and 1000.  When \fBinit_color\fR is used, all
+\fBuse_default_colors\fR(3X) routine.
+.SS init_extended_pair
+.PP
+Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pairs and color-values
+to 32767 on modern hardware.
+The extension \fBinit_extended_pair\fP uses \fBint\fPs
+for the color-pair and color-value,
+allowing a larger number of colors to be supported.
+.SS init_color
+.PP
+The \fBinit_color\fR routine changes the definition of a color.
+It takes four arguments:
+the number of the color to be changed followed by three RGB values
+(for the amounts of red, green, and blue components).
+.bP
+The first argument must be a legal color value;
+default colors are not allowed here.
+(See the section \fBColors\fR for the default color index.)
+.bP
+Each of the last three arguments
+must be a value in the range \fB0\fP through \fB1000\fP.
+.PP
+When \fBinit_color\fR is used, all
 occurrences of that color on the screen immediately change to the new
 definition.
+.SS init_extended_color
 .PP
-The \fBhas_colors\fR routine requires no arguments.  It returns \fBTRUE\fR if
-the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.  This
-routine facilitates writing terminal-independent programs.  For example, a
-programmer can use it to decide whether to use color or some other video
-attribute.
-.PP
-The \fBcan_change_color\fR routine requires no arguments.  It returns
-\fBTRUE\fR if the terminal supports colors and can change their definitions;
-other, it returns \fBFALSE\fR.  This routine facilitates writing
-terminal-independent programs.
+Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBinit_extended_color\fP uses \fBint\fPs
+for the color value and
+for setting the red, green, and blue components,
+allowing a larger number of colors to be supported.
+.SS color_content
 .PP
 The \fBcolor_content\fR routine gives programmers a way to find the intensity
-of the red, green, and blue (RGB) components in a color.  It requires four
-arguments: the color number, and three addresses of \fBshort\fRs for storing
+of the red, green, and blue (RGB) components in a color.
+It requires four arguments: the color number, and three addresses
+of \fBshort\fRs for storing
 the information about the amounts of red, green, and blue components in the
-given color.  The value of the first argument must be between 0 and
-\fBCOLORS\fR.  The values that are stored at the addresses pointed to by the
-last three arguments are between 0 (no component) and 1000 (maximum amount of
-component).
+given color.
+.bP
+The first argument must be a legal color value, i.e.,
+\fB0\fP through \fBCOLORS\-1\fP, inclusive.
+.bP
+The values that are stored at the addresses pointed to by the
+last three arguments are in the range
+\fB0\fP (no component) through \fB1000\fP
+(maximum amount of component), inclusive.
+.SS extended_color_content
+.PP
+Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBextended_color_content\fP uses \fBint\fPs
+for the color value and
+for returning the red, green, and blue components,
+allowing a larger number of colors to be supported.
+.SS pair_content
 .PP
 The \fBpair_content\fR routine allows programmers to find out what colors a
-given color-pair consists of.  It requires three arguments: the color-pair
+given color-pair consists of.
+It requires three arguments: the color-pair
 number, and two addresses of \fBshort\fRs for storing the foreground and the
-background color numbers.  The value of the first argument must be between 1
-and \fBCOLOR_PAIRS\-1\fR.  The values that are stored at the addresses pointed
-to by the second and third arguments are between 0 and \fBCOLORS\fR.
-.SS Colors
-In \fB<curses.h>\fR the following macros are defined.  These are the default
-colors.  \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
-background color for all terminals.
+background color numbers.
+.bP
+The first argument must be a legal color value,
+i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
+.bP
+The values that are stored at the addresses pointed
+to by the second and third arguments are in the
+range \fB0\fP through \fBCOLORS\fR, inclusive.
+.SS extended_pair_content
 .PP
-.nf
-      \fBCOLOR_BLACK\fR
-      \fBCOLOR_RED\fR
-      \fBCOLOR_GREEN\fR
-      \fBCOLOR_YELLOW\fR
-      \fBCOLOR_BLUE\fR
-      \fBCOLOR_MAGENTA\fR
-      \fBCOLOR_CYAN\fR
-      \fBCOLOR_WHITE\fR
-.fi
+Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pair and color-values to 32767 on modern hardware.
+The extension \fBextended_pair_content\fP uses \fBint\fPs
+for the color pair and
+for returning the foreground and background colors,
+allowing a larger number of colors to be supported.
+.SS reset_color_pairs
+.PP
+The extension \fBreset_color_pairs\fP tells ncurses to discard all
+of the color-pair information which was set with \fBinit_pair\fP.
+It also touches the current- and standard-screens, allowing an application to
+switch color palettes rapidly.
+.SS PAIR_NUMBER
+.PP
+\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
+value from its \fIattrs\fP parameter and returns it as a color pair number.
+.SS COLOR_PAIR
+Its inverse \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR converts a color pair number
+to an attribute.
+Attributes can hold color pairs in the range 0 to 255.
+If you need a color pair larger than that, you must use functions
+such as \fBattr_set\fP (which pass the color pair as a separate parameter)
+rather than the legacy functions such as \fBattrset\fP.
 .SH RETURN VALUE
-The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
+The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
 or \fBFALSE\fR.
 .PP
 All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
-(SVr4 specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+(SVr4 specifies only \*(``an integer value
+other than \fBERR\fR\*('') upon successful completion.
 .PP
 X/Open defines no error conditions.
+SVr4 does document some error conditions which apply in general:
+.bP
 This implementation will return \fBERR\fR on attempts to
-use color values outside the range 0 to COLORS\-1
+use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
 (except for the default colors extension),
-or use color pairs outside the range 0 to COLOR_PAIR\-1.
-Color values used in \fBinit_color\fP must be in the range 0 to 1000.
+or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
+.IP
+Color values used in \fBinit_color\fP must be
+in the range \fB0\fP to \fB1000\fP.
+.IP
 An error is returned from all functions
 if the terminal has not been initialized.
+.IP
 An error is returned from secondary functions such as \fBinit_pair\fP
 if \fBstart_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
+using \fBinit_pairs\fP
+and 
+it returns \fBERR\fP from \fBcolor_content\fP
+if the terminal does not support changing colors.
+.IP
+This implementation does not return \fBERR\fP for either case.
+.PP
+Specific functions make additional checks:
 .RS 3
 .TP 5
 \fBinit_color\fP
 returns an error if the terminal does not support
-this feature, e.g., if the \fIinitialize_color\fP capability is absent
+this feature, e.g., if the \fBinitialize_color\fP capability is absent
 from the terminal description.
 .TP 5
 \fBstart_color\fP
 returns an error if the color table cannot be allocated.
 .RE
 .SH NOTES
-In the \fIncurses\fR implementation, there is a separate color activation flag,
-color palette, color pairs table, and associated COLORS and COLOR_PAIRS counts
+In the \fBncurses\fR implementation, there is a separate color activation flag,
+color palette, color pairs table,
+and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
 for each screen; the \fBstart_color\fR function only affects the current
-screen.  The SVr4/XSI interface is not really designed with this in mind, and
+screen.
+The SVr4/XSI interface is not really designed with this in mind, and
 historical implementations may use a single shared color palette.
 .PP
-Note that setting an implicit background color via a color pair affects only
-character cells that a character write operation explicitly touches.  To change
+Setting an implicit background color via a color pair affects only
+character cells that a character write operation explicitly touches.
+To change
 the background color used when parts of a window are blanked by erasing or
 scrolling operations, see \fBcurs_bkgd\fR(3X).
 .PP
-Several caveats apply on 386 and 486 machines with VGA-compatible graphics:
+Several caveats apply on older x86 machines
+(e.g., i386, i486) with VGA-compatible graphics:
 .bP
-COLOR_YELLOW is actually brown.  To get yellow, use COLOR_YELLOW combined with
-the \fBA_BOLD\fR attribute.
+COLOR_YELLOW is actually brown.
+To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.
 .bP
-The A_BLINK attribute should in theory cause the background to go bright.  This
-often fails to work, and even some cards for which it mostly works (such as the
+The A_BLINK attribute should in theory cause the background to go bright.
+This often fails to work, and even some cards for which it mostly works
+(such as the
 Paradise and compatibles) do the wrong thing when you try to set a bright
-"yellow" background (you get a blinking yellow foreground instead).
+\*(``yellow\*('' background (you get a blinking yellow foreground instead).
 .bP
 Color RGB values are not settable.
 .SH PORTABILITY
@@ -224,17 +472,28 @@ This implementation satisfies XSI Curses's minimum maximums
 for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
 .PP
 The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fP extension,
+and background color to support the \fBuse_default_colors\fR(3X) extension,
 but only if that routine has been first invoked.
 .PP
 The assumption that \fBCOLOR_BLACK\fR is the default
 background color for all terminals can be modified using the
-\fBassume_default_colors\fP extension.
+\fBassume_default_colors\fR(3X) extension.
 .PP
 This implementation checks the pointers,
 e.g., for the values returned by
 \fBcolor_content\fP and \fBpair_content\fP,
 and will treat those as optional parameters when null.
+.PP
+X/Open Curses does not specify a limit for the number of colors and
+color pairs which a terminal can support.
+However, in its use of \fBshort\fP for the parameters,
+it carries over SVr4's implementation detail for the compiled
+terminfo database, which uses signed 16-bit numbers.
+This implementation provides extended versions of those functions
+which use \fBshort\fP parameters,
+allowing applications to use larger color- and pair-numbers.
+.PP
+The \fBreset_color_pairs\fP function is an extension of ncurses.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),