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

Hi Fabien,

On Sun, 10 Mar 2019 08:15:35 +0100 (CET)
Fabien COELHO <coel

> I registered as a reviewer in the CF app.

Thanks.

What's causing problems here is that the encode and decode
functions are listed in both the string functions section
and the binary functions section.  A related but not-relevant
problem is that there are functions listed in the string
function section which take binary input.

I asked about this on IRC and the brief reply was
unflattering to the existing documentation.

So I'm going to fix this also.  3 patches attached:

doc_base64_part1_v9.patch

  This moves functions taking bytea and other non-string
  input into the binary string section, and vice versa.
  Eliminates duplicate encode() and decode() documentation.

  Affects: convert(bytea, name, name)
           convert_from(bytea, name)
           encode(bytea, text)
           length(bytea, name)
           quote_nullable(anytype)
           to_hex(int or bigint)
           decode(text, text)

  Only moves, eliminates duplicates, and adjusts indentation.


doc_base64_part2_v9.patch

  Cleanup wording after moving functions between sections.


doc_base64_part3_v9.patch

  Documents base64, hex, and escape encode() and decode()
  formats.

> >> "The string and the binary encode and decode functions..." sentence
> >> looks strange to me, especially with the English article that I do
> >> not really master, so maybe it is ok. I'd have written something
> >> more straightforward, eg: "Functions encode and decode support the
> >> following encodings:",  
> >
> > It is an atypical construction because I want to draw attention
> > that this is documentation not only for the encode() and decode()
> > in section 9.4. String Functions and Operators but also for the
> > encode() and decode in section 9.5. Binary String Functions and
> > Operators. Although I can't think of a better approach it makes me
> > uncomfortable that documentation written in one section applies
> > equally to functions in a different section.  
> 
> People coming from the binary doc would have no reason to look at the 
> string paragraph anyway.
> 
> > Do you think it would be useful to hyperlink the word "binary"
> > to section 9.5?  
> 
> Hmmm... I think that the link is needed in the other direction.

I'm not sure what you mean here or if it's still relevant.

> I'd suggest (1) to use a simpler and direct sentence in the string 
> section, (2) to simplify/shorten the in cell description in the
> binary section, and (3) to add an hyperlink from the binary section
> which would point to the expanded explanation in the string section.
> 
> > The idiomatic phrasing would be "Both the string and the binary
> > encode and decode functions..." but the word "both" adds
> > no information.  Shorter is better.  
> 
> Possibly, although "Both" would insist on the fact that it applies to
> the two variants, which was your intention.

I think this is no longer relevant.  Although I'm not sure what
you mean by 3.  The format names already hyperlink back to the
string docs.

> >> and also I'd use a direct "Function
> >> <...>decode</...> ..." rather than "The <function>decode</function>
> >> function ..." (twice).  
> >
> > The straightforward English would be "Decode accepts...".  The
> > problem is that this begins the sentence with the name of a
> > function. This does not work very well when the function name is
> > all lower case, and can have other problems where clarity is lost
> > depending on documentation output formatting.  
> 
> Yep.
> 
> > I don't see a better approach.  
> 
> I suggested "Function <>decode</> ...", which is the kind of thing we
> do in academic writing to improve precision, because I thought it
> could be better:-)

"Function <>decode</> ..." just does not work in English.

> >> Maybe I'd use the exact same grammatical structure for all 3 cases,
> >> starting with "The <>whatever</> encoding converts bla bla bla"
> >> instead of varying the sentences.  
> >
> > Agreed.  Good idea.  The first paragraph of each term has to
> > do with encoding and the second with decoding.  
> 
> 
> > Uniformity in starting the second paragraphs helps make
> > this clear, even though the first paragraphs are not uniform.
> > With this I am not concerned that the first paragraphs
> > do not have a common phrasing that's very explicit about
> > being about encoding.
> >
> > Adjusted.  
> 
> Cannot see it fully in the v8 patch:
> 
>   - The <literal>base64</literal> encoding is
>   - <literal>hex</literal> represents
>   - <literal>escape</literal> converts

I did only the decode paras.  I guess no reason not to make
the first paras uniform as well.   Done.

I also alphabetized by format name.

I hope that 3 patches will make review easier.

Regards,

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