I've pushed this patch with some further hacking.
Most notably, I shoved the conversion-names table over to charset.sgml,
as I'd mused about doing upthread. It no longer had any reason at all
to be in section 9.4. We could have moved it down to 9.5, but I felt
that it would still be wrongly placed there. Since none of these
functions actually take conversion names, it's not very relevant
documentation for them --- you can generally assume that whatever
conversion you want is available, and you'll usually be right.
Another point relevant to the discussion is that I dropped the <sect2>
for the conversion functions. It seemed to me that giving them their
own table was enough --- the discussion about them isn't lengthy enough
to justify a separate section, IMO. I also don't buy the argument that
we need a <sect2> to make these things visible in the table of contents.
We have the cross-reference from section 9.4, as well as a passel of
index entries, to help people who don't know where to look. (Once upon
a time we had a list of tables alongside the TOC; maybe that should be
resurrected?)
I took the liberty of doing some copy-editing on nearby function
descriptions, too, mostly to try to give them more uniform style.
And there were some errors; notably, the patch added descriptions
for shaNNN(text), which are functions we do not have AFAICS.
I share Alvaro's feeling that these tables could stand to be reformatted
so that they're not such a mess when rendered in narrower formats. But
that seems like a task for a separate patch, especially since the problem
is hardly confined to these two sections.
regards, tom lane
