adding return argument

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@123214 c90b9560-bf6c-de11-be94-00142212c4b1

reference/var/functions/print-r.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/var.xml, last change in rev 1.5 -->
   <refentry id="function.print-r">
    <refnamediv>
@@ -13,7 +13,13 @@
      <methodsynopsis>
       <type>bool</type><methodname>print_r</methodname>
       <methodparam><type>mixed</type><parameter>expression</parameter></methodparam>
+      <methodparam choice="opt"><type>bool</type><parameter>return</parameter></methodparam>
      </methodsynopsis>
+    <note>
+     <simpara>
+      The <parameter>return</parameter> parameter was added in PHP 4.3.0
+     </simpara>
+    </note>
     <simpara>
      <function>print_r</function> displays information about a variable
      in a way that's readable by humans.  If given a <type>string</type>,
@@ -27,7 +33,6 @@
      pointer to the end. Use <function>reset</function> to bring
      it back to beginning.
     </simpara>
-     &tip.ob-capture;
     <para>
      <informalexample>
       <programlisting role="php">
@@ -60,8 +65,34 @@ Array
 )
 </pre>
 ]]>
-      </screen>
-     </para>
+     </screen>
+    </para>
+    <para>
+     If you would like to capture the output of <function>print_r</function>, 
+     use the <parameter>return</parameter> parameter.  If this parameter is set
+     to &true;, <function>print_r</function> will return its output, instead of
+     printing it (which it does by default).
+    </para>
+    <para>
+     <example>
+      <title><parameter>return</parameter> parameter example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+    $b = array ('m' => 'monkey', 'foo' => 'bar', 'x' => array ('x', 'y', 'z'));
+    $results = print_r ($b, true); //$results now contains output from print_r
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+    <note>
+     <simpara>
+      If you need to capture the output of <function>print_r</function> with a
+      version of PHP prior to 4.3.0, use the <link linkend="ref.outcontrol">
+      output-control functions</link>.
+     </simpara>
+    </note>
     <note>
      <simpara>
       Prior to PHP 4.0.4, <function>print_r</function> will continue forever