Re: Patch to document base64 encoding

[Karl O. Pinc]

On Tue, 5 Mar 2019 07:26:17 -0600
"Karl O. Pinc" <k...@meme.com> wrote:

> (I am not entirely pleased with the double dash
> but can't come up with anything better.  And
> can't make an emdash entity work either.)

Attached: doc_base64_v3.patch

There is an mdash entity.  This patch uses that.

Regards,

Karl <k...@meme.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6765b0d584..e5ae322faa 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1752,6 +1752,9 @@
         <indexterm>
          <primary>decode</primary>
         </indexterm>
+        <indexterm>
+         <primary>base64</primary>
+        </indexterm>
         <literal><function>decode(<parameter>string</parameter> <type>text</type>,
         <parameter>format</parameter> <type>text</type>)</function></literal>
        </entry>
@@ -1769,13 +1772,16 @@
         <indexterm>
          <primary>encode</primary>
         </indexterm>
+        <indexterm>
+         <primary>base64</primary>
+        </indexterm>
         <literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
         <parameter>format</parameter> <type>text</type>)</function></literal>
        </entry>
        <entry><type>text</type></entry>
        <entry>
         Encode binary data into a textual representation.  Supported
-        formats are: <literal>base64</literal>, <literal>hex</literal>, <literal>escape</literal>.
+        formats are: <link linkend="base64-encoding"><literal>base64</literal></link>, <literal>hex</literal>, <literal>escape</literal>.
         <literal>escape</literal> converts zero bytes and high-bit-set bytes to
         octal sequences (<literal>\</literal><replaceable>nnn</replaceable>) and
         doubles backslashes.
@@ -2365,6 +2371,21 @@
     <function>format</function> treats a NULL as a zero-element array.
    </para>
 
+   <indexterm>
+     <primary>base64</primary>
+   </indexterm>
+
+   <para id="base64-encoding">
+     The base64 encoding of the <function>encode</function>
+     and <function>decode</function> functions is that of RFC2045 section 6.8.
+     As per the RFC, encoded lines are broken at 76 characters.  However
+     instead of the MIME CRLF end-of-line marker, only a newline is used for
+     end-of-line.  The carriage-return, newline, space, and tab characters are
+     ignored by <function>decode</function>.  Otherwise, an error is raised
+     when <function>decode</function> is supplied invalid base64 data &mdash;
+     including when trailing padding is incorrect.
+   </para>
+
    <para>
    See also the aggregate function <function>string_agg</function> in
    <xref linkend="functions-aggregate"/>.
@@ -3577,13 +3598,16 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         <indexterm>
          <primary>encode</primary>
         </indexterm>
+        <indexterm>
+         <primary>base64</primary>
+        </indexterm>
        <literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
        <parameter>format</parameter> <type>text</type>)</function></literal>
       </entry>
       <entry><type>text</type></entry>
       <entry>
        Encode binary data into a textual representation.  Supported
-       formats are: <literal>base64</literal>, <literal>hex</literal>, <literal>escape</literal>.
+       formats are: <link linkend="base64-encoding"><literal>base64</literal></link>, <literal>hex</literal>, <literal>escape</literal>.
        <literal>escape</literal> converts zero bytes and high-bit-set bytes to
        octal sequences (<literal>\</literal><replaceable>nnn</replaceable>) and
        doubles backslashes.