Documentation patch for date/time formatting functions - Mailing list pgsql-hackers

Due to a variety of messages over time regarding perceived weirdness in 
to_timestamp and to_date, this patch adds "(see notes)" in the 
description column for to_date and to_timestamp in the Formatting 
Functions table and adds the following text to the opening of the usage 
notes for date/time conversion:

The to_date and to_timestamp functions exist to handle unusual input 
formats that cannot be converted by simple casting.  These functions 
interpret input liberally and with minimal error checking and while they 
will produce valid output, the conversion has the potential to yield 
unexpected results.  Read the following notes and test carefully before 
use.  Casting is the preferred method of conversion wherever possible.

It also adds the following usage note:

Input to to_date and to_timestamp is not restricted to normal ranges 
thus to_date('20096040','YYYYMMDD') returns 2014-01-17 rather than 
causing an error.

This is the first patch I have submitted directly. Please advise if I 
have made any errors in method, style, etc.

Cheers,
Steve

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index a1d3aee..6f5eee0 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -5426,7 +5426,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<literal><function>to_date(<type>text</type>, 
<type>text</type>)</function></literal>         </entry>         <entry><type>date</type></entry>
-        <entry>convert string to date</entry>
+        <entry>convert string to date (see notes)</entry>
<entry><literal>to_date('05 Dec 2000', 
'DD Mon YYYY')</literal></entry>        </row>        <row>
@@ -5448,7 +5448,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<literal><function>to_timestamp(<type>text</type>, 
<type>text</type>)</function></literal>         </entry>         <entry><type>timestamp with time zone</type></entry>
-        <entry>convert string to time stamp</entry>
+        <entry>convert string to time stamp (see notes)</entry>
<entry><literal>to_timestamp('05 Dec 2000', 
'DD Mon YYYY')</literal></entry>        </row>        <row>
@@ -5750,10 +5750,27 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
    <para>     Usage notes for date/time formatting:
-
+   </para>
+   <para>
+    The <function>to_date</function> and <function>to_timestamp<function>
+    functions exist to handle unusual input formats that cannot be
+    converted by simple casting.  These functions interpret input 
liberally
+    and with minimal error checking and while they will produce valid 
output,
+    the conversion has the potential to yield unexpected results. Read the
+    following notes and test carefully before use.  Casting is the
+    preferred method of conversion wherever possible.     <itemizedlist>      <listitem>       <para>
+       Input to <function>to_date</function> and
+       <function>to_timestamp<function> is not restricted to normal ranges
+       thus <literal>to_date('20096040','YYYYMMDD')</literal> returns
+       <literal>2014-01-17</literal> rather than causing an error.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>        <literal>FM</literal> suppresses leading zeroes and trailing 
blanks        that would otherwise be added to make the output of a pattern be        fixed-width.  In
<productname>PostgreSQL</productname>,