Re: Patch to document base64 encoding

Er, ping.  Nobody has reviewed the latest patchs.
They still apply to master...

I am re-attaching the patches.  See descriptions
below.

On Mon, 11 Mar 2019 15:32:14 -0500
"Karl O. Pinc" <kop@meme.com> wrote:

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

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


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