Re: Patch to document base64 encoding

Hello Karl,

> doc_base64_part1_v9.patch
> 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.

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

It really works in research papers: "Theorem X can be proven by applying
Proposition Y. See Figure 2 for details. Algorithm Z describes whatever,
which is listed in Table W..."

> I also alphabetized by format name.

Good:-)

> I hope that 3 patches will make review easier.

Not really. I'm reviewing the 3 patches put together rather than each one
individually, which would require more work.

Patch applies cleanly. Doc build ok.

I looked at the html output, and it seems ok, including navigating to
conversions or formats explanations.

This documentation patch is an overall improvement and clarifies things,
including some error conditions.

convert: I'd merge the 2 first sentences to state that if convert from X
to Y. The doc does not say explicitely what happens if a character cannot
be converted. After testing, an error is raised. The example comment could
add ", if possible".

to_hex: add "." at the end of the sentence?

Other descriptions seem ok.

Minor comment: you usually put two spaces between a "." and the first
world of then next sentence, but not always.

--
Fabien.