From 3b76e4547ba7cb8e52089742ae4aaa54a1fe739d Mon Sep 17 00:00:00 2001
From: Regina Obe <lr@pcorp.us>
Date: Sat, 5 Jul 2014 04:17:37 +0000
Subject: [PATCH] #2810 document the delimeter argument and big warning to
 avoid because we may remove it in future versions

git-svn-id: http://svn.osgeo.org/postgis/trunk@12726 b70326c6-7e19-0410-871a-916f4a2858ee
---
 doc/reference_raster.xml | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index f38678973..0ac5558aa 100644
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -1607,14 +1607,14 @@ SELECT ST_AsPNG(
 				  <funcprototype>
 					<funcdef>raster <function>ST_Band</function></funcdef>
 					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
-					<paramdef><type>text </type> <parameter>nbands</parameter></paramdef>
-					<paramdef choice="opt"><type>character </type> <parameter>delimiter=,</parameter></paramdef>
+					<paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
 				  </funcprototype>
 				  
-				  <funcprototype>
+				<funcprototype>
 					<funcdef>raster <function>ST_Band</function></funcdef>
 					<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
-					<paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+					<paramdef><type>text </type> <parameter>nbands</parameter></paramdef>
+					<paramdef choice="opt"><type>character </type> <parameter>delimiter=,</parameter></paramdef>
 				  </funcprototype>
 				</funcsynopsis>
 			</refsynopsisdiv>
@@ -1622,8 +1622,9 @@ SELECT ST_AsPNG(
 			<refsection>
 				<title>Description</title>
 				
-				<para>Returns a single band of an existing raster as a new raster.  Useful for building new rasters from existing rasters or export of only selected
-				bands of a raster. If no band is specified, band 1 is assumed. Used as a helper function in various functions such as for deleting a band.</para>
+				<para>Returns one or more bands of an existing raster as a new raster.  Useful for building new rasters from existing rasters or export of only selected
+				bands of a raster or rearranging the order of bands in a raster. If no band is specified, band 1 is assumed. Used as a helper function in various functions such as for deleting a band. </para>
+				<warning><para>For the <code>nbands</code> as text variant of function, the default delimiter is <code>,</code> which means you can ask for <code>'1,2,3'</code> and if you wanted to use a different delimeter you would do <code>ST_Band(rast, '1@2@3', '@')</code>.  For asking for multiple bands, we strongly suggest you use the array form of this function e.g. <code>ST_Band(rast, '{1,2,3}'::int[]);</code> since the <code>text</code> list of bands form may be removed in future versions of PostGIS.</para></warning>
                     
                  <para>Availability: 2.0.0</para>
 			</refsection>
@@ -1644,8 +1645,8 @@ FROM (
      1 | 8BUI |     1 | 2BUI
 					</programlisting>
 					
-					<programlisting>-- Return bands 2 and 3. Use text to define bands
-SELECT ST_NumBands(ST_Band(rast, '2,3')) As num_bands
+					<programlisting>-- Return bands 2 and 3. Using array cast syntax
+SELECT ST_NumBands(ST_Band(rast, '{2,3}'::int[])) As num_bands
     FROM dummy_rast WHERE rid=2;
     
 num_bands
@@ -1704,7 +1705,7 @@ WHERE rid=35;
 
 			<refsection>
 				<title>See Also</title>
-				<para><xref linkend="RT_ST_AddBand" />, <xref linkend="RT_ST_NumBands" />, , <xref linkend="RT_ST_Reclass" /></para>
+				<para><xref linkend="RT_ST_AddBand" />, <xref linkend="RT_ST_NumBands" />, <xref linkend="RT_ST_Reclass" />, <xref linkend="RT_reference" /></para>
 			</refsection>
 		</refentry>
 
-- 
2.50.0