"Karl O. Pinc" <kop@karlpinc.com> writes:
> On Mon, 15 Jul 2019 23:00:55 +0200 (CEST)
> Fabien COELHO <coelho@cri.ensmp.fr> wrote:
>> The patch clarifies the documentation about encode/decode and other
>> text/binary string conversion functions.
> Other notable changes:
> Corrects categorization of functions as string or binary.
> Reorders functions alphabetically by function name.
So I took a look at this, expecting that after so much discussion it
ought to just be committable ... but I am befuddled by your choices
about which functions to move where. It seems entirely crazy that
encode() and decode() are no longer in the same section, likewise that
convert_from() and convert_to() aren't documented together anymore.
I'm not sure what is the right dividing line between string and binary
functions, but I don't think that anyone is going to find this
division helpful.
I do agree that documenting some functions twice is a bad plan,
so we need to clean this up somehow.
After some thought, it seems like maybe a workable approach would be
to consider that all conversion functions going between text and
bytea belong in the binary-string-functions section. I think it's
reasonable to say that plain "string functions" just means stuff
dealing with text.
Possibly we could make a separate table in the binary-functions
section just for conversions, although that feels like it might be
overkill.
While we're on the subject, Table 9.11 (conversion names) seems
entirely misplaced, and I don't just mean that it would need to
migrate to the binary-functions page. I don't think it belongs
in func.sgml at all. Isn't it pretty duplicative of Table 23.2
(Client/Server Character Set Conversions)? I think we should
unify it with that table, or at least put it next to that one.
Perhaps that's material for a separate patch though.
regards, tom lane
