Re: Patch to document base64 encoding

Hello Karl,

I registered as a reviewer in the CF app.

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

>> 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:-)

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

>> Otherwise, all explanations look both precise and useful to me.
>
> When writing I was slightly concerned about being overly precise;

Hmmm. That is a technical documentation, a significant degree of precision
is expected.

--
Fabien.