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(at)meme(dot)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(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein