Re: Patch to document base64 encoding

Hello Karl,

> New patch attached: doc_base64_v13.patch
>
> This required surprisingly little re-wording.
> Added word "binary" into the descriptions of convert(),
> substring(), convert_from(), and convert_to().
>
> I also added data types to the call syntax of set_bit()
> and set_byte().
>
> And this patch adds hyperlinks from the get_bit(), get_byte(),
> set_bit(), and set_byte() descriptions to the note
> that offsets are zero-based.
>
> I also removed the hyperlinked asterisks about the hash
> function results and instead hyperlinked the word "hash"
> in the descriptions. (Links to the note about md5()
> returning hex text and the others returning bytea and how
> to convert between the two.)

Patch applies cleanly and compiles.

My 0.02€: The overall restructuration and cross references is an
improvement.

Some comments about v13:

The note about get_byte reads:

get_byte and set_byte number the first byte of a binary string as byte
0. get_bit and set_bit number bits from the right within each byte; for
example bit 0 is the least significant bit of the first byte, and bit 15
is the most significant bit of the second byte.

The two sentences starts with a lower case letter, which looks strange to
me. I'd suggest to put "Functions" at the beginning of the sentences:

Functions get_byte and set_byte number the first byte of a binary string
as byte 0. Functions get_bit and set_bit number bits from the right
within each byte; for example bit 0 is the least significant bit of the
first byte, and bit 15 is the most significant bit of the second byte.

The note about hash provides an example for getting the hex representation
out of sha*. I'd add an exemple to get the bytea representation from md5,
eg "DECODE(MD5('hello world'), 'hex')"…

Maybe the encode/decode in the note could be linked to the function
description? Well, they are just after, maybe it is not very useful.

The "Binary String Functions and Operators" 9.5 section has only one
subsection, "9.5.1", which is about at two thirds of the page. This
structure looks weird. ISTM that a subsection is missing for the beginning
of the page, or that the subsection should just be dropped, because it is
somehow redundant with the table title.

The "9.4" section has the same structural weirdness. Either remove the
subsection, or add some for the other parts?

--
Fabien.