Re: Patch to document base64 encoding

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