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

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.