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

Hello Fabien,

On Sun, 5 Jan 2020 12:48:59 +0100 (CET)
Fabien COELHO <coelho@cri.ensmp.fr> wrote:

> I'm in favor of moving and reorganizing these function descriptions,
> as they are somehow scattered with a unclear logic when you are
> looking for them.

I assume by this you mean you are happy with the organization done
by the patch.

For review (I think I've got this right) the organizational
changes are:

The changes suggested by Tom where 2
functions with the same name, one of which takes string 
arguments and the other of which takes bytea arguments
now show up both in the doc section on string functions and
in the doc section on bytea functions.

I believe I also alphabetized the binary function ordering.  

And this patch introduces a separate table/sub-section for 
functions which convert between binary and string.)
There are much-expanded descriptions of encode()
and decode().  (Which is how this patch series
started, explaining base64 encoding/decoding.)

FYI.  There is also an unusual usage of a hyperlinked
asterisk following the returned datatype of the hash
functions.  The hyperlink leads to the historical
note on the datatype used for the md5() function v.s.
the other hash functions.

>   +       <entry><literal><parameter>bytea</parameter>
> <literal>||</literal>
>   +        <parameter>bytea</parameter></literal></entry>
>           <entry> <type>bytea</type> </entry>
>           <entry>
>            String concatenation
> 
> Bytea concatenation?

Done.  (Could just say "Concatenation" I suppose.  But "Bytea
concatenation" does not hurt and would be nice if you
ever looked at the tables for string operators and bytea
operators side-by-side.)

> I'm not keen on calling the parameter the name of its type. I'd
> suggest to keep "string" as a name everywhere, which is not a type
> name in Pg.
> 
> The functions descriptions are not homogeneous. Some have parameter
> name & type "btrim(string bytea, bytes bytea)" and others only type
> or parameter with tagged as a parameter "get_bit(bytea,
> offset)" (first param), "sha224(bytea)".
> 
> I'd suggest to be consistent, eg use "string bytea" everywhere 
> appropriate.

Ok.  Done.  Except that I've left the encode() function
as encode(data bytea, format text) because the whole
point is to convert _to_ a string/text datatype
from something that's _not_ a string.  Calling
the input a string just seems wrong.  This inconsistency seems ok
because encode() is in the table of string <-> bytea functions,
away from the other bytea functions.


If you're interested, another possibility would be the
consistent use of "data bytea" everywhere.  I like this
choice because it works well to write
encode(<parameter>data</parameter> bytea,
       <parameter>format</parameter text), and probably
works well in other places too.  But then the word
"string" does not really fit in a lot of the descriptions.
So this choice would involve re-writing descriptions so
that the existing description:

  btrim(<parameter>string</parameter> bytea,
        <parameter>bytes</parameter> bytea)

    Remove the longest string containing only bytes appearing in
    <parameter>bytes</parameter> from the start and end of
    <parameter>string</parameter>


Would change to (say):

  btrim(<parameter>data</parameter> bytea,
        <parameter>bytes</parameter> bytea)

  Remove the longest contiguous sequence of bytes containing only
  those bytes appearing in <parameter>bytes</parameter>
  from the start and end of <parameter>data</parameter>

The trouble with using "data bytea" is that there might
need to be adjustments to the word "string" elsewhere in
the section, not just in the descriptions.

Let me know if you'd prefer "data bytea" to "string bytea"
and consequent frobbing of descriptions.  That might be
out-of-scope for this patch.  (Which is already
a poster-child for feature-creep.)

Attached is doc_base64_v12.patch.

Regards,

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