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.