Re: Patch to document base64 encoding - Mailing list pgsql-hackers

On Tue, 30 Jul 2019 11:40:03 -0400
Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "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 ...

It started simple, just changing the base64 function descriptions,
but critique drew in additional issues.

> but I am befuddled by your choices
> about which functions to move where. 

The grouping is by the data type on which each function operates,
the data type of the input.

If there's to be 2 categories, as in the
existing docs, it seems to me that you have to categorize either by
the data type input or data type output.  To categorize by input
and output together would result 4 (or more?) categories, which
would be even crazier.

> 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.

Awkward, yes.  But findable if you know what the categories are.

I suppose there could be 3 different categories: those that input
and output strings, those that input and output binary, and those
that convert -- inputting one data type and outputting another.

I'm not sure that this would really address the issue of documenting,
say encode() and decode() together.  It pretty much makes sense to
alphabetize the functions _within_ each category, because that's
about the only easily defined way to do it.  Going "by feel" and
putting encode() and decode() together raises the question of
where they should be together in the overall ordering within
the category.

> 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.

Maybe there's a way to make more clear what the categories are?
I could be explicit in the description of the section.

> 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.

Ok.  Should the section title remain unchanged?
"Binary String Functions and Operators"

I think the summary description of the section will need
a little clarification.

> Possibly we could make a separate table in the binary-functions
> section just for conversions, although that feels like it might be
> overkill.

I have no good answers.  An advantage to a separate section
for conversions is that you _might_ be able to pair the functions,
so that encode() and decode() do show up right next to each other.

I'm not sure exactly how to structure "pairing".  I would have to
play around and see what might look good.

> 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.

I don't know.  But it does seem something that can be addressed
in isolation and suitable for it's own patch.

Thanks for the help.  I will wait for a response to this
before submitting another patch, just in case someone sees any
ideas here to be followed up on.

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein