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.
