MANUAL.md: text attribute update

[GitMensch]

• reformatting for markdown (the old version was broken concerning the bits)
• reordered to have common notes before going into details

There are a bunch of other changes the manual may need an update to be nicely shown as markdown (starting with C code blocks, going on with more structuring, ... but that will take some time (and is a task I may be up to if we can agree on those changes up-front).

[GitMensch]

... Just thinking about changes I may applyI see that this reformatting and adjustment seems like a task an insstructed LLM could handle well, so my task would be "only" the instructions and checking the diff... that would at least be faster.
Is that something that woulds be considered fine (PDC is public domain, but before I use LLM for such a global change to the doc, I still like to ask, after all I can do that myself as well [and no one should do task with an LLM he cannot do, but that's a side rant]).

[Bill-Gray]

Seems like a good idea. A couple of small hitches, though.

MANUAL.md is built automatically, by searching for text in the source files, using docs/mkman.sh. That hasn't been done for about a year, and the existing MANUAL.md lacked some updates concerning the panel library and three newer multi-byte to wide-character (and vice versa) functions. I just added commit 6f719c7 to bring it up to date. (Fortunately, that doesn't conflict with what you've done.)

However, the changes/reorganization in comments about attribute bits should be done in curses.h, and docs/mkman.sh then run so that the changes get reflected in MANUAL.md.

I noticed a while back that @wmcbrine has done some work to make the manual more markdown-friendly (table display, for example). We may want to cherry-pick commits such as wmcbrine/PDCurses@aa8d315f, wmcbrine/PDCurses@574895223, wmcbrine/PDCurses@26f39dec9, wmcbrine/PDCurses@2d5ddb75b, and some of their predecessors... he did quite a bit there.

I'm deeply skeptical of so-called "AI". But this is a case where I'd think you could give it a try, and the changes would be such that we could look at it and either say "oh, heck no", or grudgingly admit that it was actually okay. I don't think copyright would be an issue.

[Bill-Gray]

Should note it's not so much a matter of "the old version was broken concerning the bits"; it's more a matter of "the old version is from a pre-Markdown universe".

[GitMensch]

Cherry pick doc work sounds good - can you give that a try?

[Bill-Gray]

Returning to this issue... the documentation in question has actually gotten a bit worse. I brought in some Markdown changes from William, and added some of my own, and added a discussion of 16-bit chtypes.

I started out by adopting much of what you had. I noticed a few mistakes I'd made ("bits 7-1" in cases where it should have been 7 to 0, plus some outdated text from before the return of 16-bit chtypes) and a lot of stuff that simply required re-writing. Here's the resulting change in curses.h (and why won't GitHub allow me to just attach that?). And here's the result after running mkman.sh... any comments, or shall I just go ahead and commit it?

Text Attributes

All chtypes have bits devoted to character data, attribute data, and color
pair data. There are four configurations supported :

Default, 64-bit chtype, both wide- and 8-bit character builds:

color pair	unused	modifiers	character eg 'a'
63 62 .. 45 44	43 .. 39	37 36 35 .. 22 21	20 19 18 .. 3 2 1 0

21 character bits (0-20), enough for full Unicode coverage
17 attribute bits (21-37)
6 currently unused bits (38-43)
20 color pair bits (44-63), enough for 1048576 color pairs

As of 2025 Dec 30, WinGUI, VT, X11 and X11new, Linux framebuffer,
DOSVGA, OpenGL, and SDLn can have COLOR_PAIRS = 1048576. Plan9 and
WinCon may join them. DOS and OS/2 lack full-color capability.

32-bit chtypes with wide characters (CHTYPE_32 and PDC_WIDE are #defined):

color pair	modifiers	character eg 'a'
31 30 29 .. 25 24	23 22 21 20 19 18 17 16	15 14 13 .. 2 1 0

16 character bits (0-16), enough for BMP (Unicode below 64K)
8 attribute bits (16-23)
8 color pair bits (24-31), for 256 color pairs

32-bit chtypes with narrow characters (CHTYPE_32 #defined, PDC_WIDE is not):

color pair	modifiers	character
31 30 29 .. 22 21 20	19 18 17 16 .. 10 9 8	7 6 5 4 3 2 1 0

8 character bits (0-7); only 8-bit charsets will work
12 attribute bits (8-19)
12 color pair bits (20-31), for 4096 pairs

16-bit chtypes (CHTYPE_16 #defined, must be narrow characters) :

color pair	modifs	character
15 14 13 12 11	10 9 8	7 6 5 4 3 2 1 0

8 character bits (0-7); only 8-bit charsets will work
3 attribute bits (8-10) : bold, reverse, blink
5 color pair bits (11-15), for 32 pairs

This is normally used only in very low-memory situations.