Re: Patch to document base64 encoding

I just wanted to throw this in the archives; this doesn't need to affect
your patch.

Because of how the new tables look in the PDF docs, I thought it might
be a good time to research how to make each function-entry occupy two
rows: one for prototype, return type and description, and the other for
the example and its result. Below is a first cut of how you'd implement
that idea -- see colspec/spanspec/spanname ... only the output looks
almost as bad (though the benefit is that it doesn't overwrite cell
contents anymore).

I think we have two choices. One is to figure out how to make this
work (ie. make it pretty; maybe by using alternate cell backgrounds, say
one white and one very light gray; maybe by using thinner/thicker
inter-cell lines); the other is to forget tables altogether and format
the info in some completely different way.

<table id="functions-binarystringconversions">
<title>Binary/String Conversion Functions</title>
<tgroup cols="4">
<colspec colnum="1" colname="col1" colwidth="1*" />
<colspec colnum="2" colname="col2" colwidth="1*" />
<colspec colnum="3" colname="col3" colwidth="1*" />
<colspec colnum="4" colname="col4" colwidth="1*" />
<spanspec spanname="cols12" namest="col1" nameend="col2" />
<spanspec spanname="cols34" namest="col3" nameend="col4" />

<thead>
<row>
<entry spanname="cols12">Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
</row>
<row>
<entry spanname="cols12">Example</entry>
<entry spanname="cols34">Result</entry>
</row>
</thead>

<tbody>
<row>
<entry spanname="cols12">
<indexterm>
<primary>convert_from</primary>
</indexterm>
<literal><function>convert_from(<parameter>bytes</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Convert binary string to the database encoding. The original encoding
is specified by <parameter>src_encoding</parameter>. The
<parameter>bytes</parameter> must be valid in this encoding. See
<xref linkend="conversion-names"/> for available conversions.
</entry>
</row>
<row>
<entry spanname="cols12"><literal>convert_from('text_in_utf8', 'UTF8')</literal></entry>
<entry spanname="cols34"><literal>text_in_utf8</literal> represented in the current database encoding</entry>
</row>

--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services