Re: 9.4. String Functions and Operators page does not document that encode adds line breaks

On Sat, Feb 8, 2020 at 12:10 PM PG Doc comments form <noreply(at)postgresql(dot)org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/12/functions-string.html
> Description:
>
> It took me a long time to discover why a base 64 encoded SHA-512 hash was
> 89
> characters long instead of the expected 88. The documentation does not
> mention that the encode function inserts newlines after 76 characters.
> Please make a note of this behavior.
>

Patch submissions are welcomed. Though there is an argument for this being
an implementation detail one shouldn't rely upon and therefore should not
be described in user-facing documentation.

> By the way, this is a very poor design decision.

It seems to be something we inherited some 20 years ago and are not likely
to change even though I suspect you will find general agreement with your
position. Though since its isn't documented maybe changing it would be ok.

The workaround of trimming whitespace characters from the encoded string is
> ugly
> and unacceptable.
>

It may be a bit ugly but when dealing with base64, specifically when
decoding, whitespace of this nature is expressly allowed. Its historical
presence here, based upon MIME requirements prevalent at the time the code
was written, doesn't alter its meaning and so it somewhat rightfully
considered an implementation detail that is not necessary to document.

David J.