diff --git a/reference/info/functions/getopt.xml b/reference/info/functions/getopt.xml
index 4661110379..2f4527198e 100644
--- a/reference/info/functions/getopt.xml
+++ b/reference/info/functions/getopt.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.16 $ -->
+<!-- $Revision: 1.17 $ -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.getopt">
  <refnamediv>
   <refname>getopt</refname>
@@ -14,9 +14,7 @@
    <methodparam choice="opt"><type>array</type><parameter>longopts</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Returns an associative array of option / argument pairs based on the
-   options format specified in <parameter>options</parameter>, or &false;
-   on an error.
+   Parses options passed to the script.
   </para>
  </refsect1>
 
@@ -27,33 +25,70 @@
     <varlistentry>
      <term><parameter>options</parameter></term>
      <listitem>
-      <para>
-       The <parameter>options</parameter> parameter may contain the following
-       elements: individual characters, and characters followed by a colon to
-       indicate an option argument is to follow.  For example, an option string
-       <literal>x</literal> recognizes an option <literal>-x</literal>, and an
-       option string <literal>x:</literal> recognizes an option and argument
-       <literal>-x argument</literal>.  It does not matter if an argument has
-       leading white space.
-      </para>
+      <simpara>
+       Each character in this string will be used as option characters and
+       matched against options passed to the script starting with a single
+       hyphen (<literal>-</literal>).
+      </simpara>
+      <simpara>
+       For example, an option string <literal>"x"</literal> recognizes an
+       option <literal>-x</literal>.
+      </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>longopts</parameter></term>
      <listitem>
-      <para>
-      </para>
+      <simpara>
+       An array of options. Each element in this array will be used as option
+       strings and matched against options passed to the script starting with
+       two hyphens (<literal>--</literal>).
+      </simpara>
+      <simpara>
+       For example, an longopts element <literal>"opt"</literal> recognizes an
+       option <literal>--opt</literal>.
+      </simpara>
+      <note>
+       <simpara>
+        Prior to PHP5.3.0 this parameter was only available on few systems
+       </simpara>
+      </note>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
+  <para>
+   The <parameter>options</parameter> parameter may contain the following
+   elements:
+   <simplelist>
+    <member>Individual characters (do not accept values)</member>
+    <member>Characters followed by a colon (parameter requires value)</member>
+    <member>Characters followed by two colons (optional value)</member>
+   </simplelist>
+   Option values are the first argument after the string. It does not matter
+   if a value has leading white space or not.
+   <note>
+    <simpara>
+     Optional values do not accept <literal>" "</literal> (space) as a seperator.
+    </simpara>
+   </note>
+  </para>
+  <note>
+   <para>
+    The format for the <parameter>options</parameter> and
+    <parameter>longopts</parameter> is almost the same, the only difference is
+    that <parameter>longopts</parameter> takes an array of options (where each
+    element is the option) where as <parameter>options</parameter> takes a
+    string (where each character is the option).
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   This function will return an array of option / argument pairs.  If an
-   option does not have an argument, the value will be set to &false;.
+   This function will return an array of option / argument pairs or &false; on
+   failure.
   </para>
  </refsect1>
 
@@ -84,25 +119,125 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
-   <example>
+   <example xml:id="getopt.examples-1">
     <title><function>getopt</function> Example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-// parse the command line ($GLOBALS['argv'])
 $options = getopt("f:hp:");
+var_dump($options);
 ?>
 ]]>
     </programlisting>
+    <para>
+     Running the above script with <literal>php script.php -fvalue -h</literal>
+     will output:
+    </para>
+    <screen>
+<![CDATA[
+array(2) {
+  ["f"]=>
+  string(5) "value"
+  ["h"]=>
+  bool(false)
+}
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example xml:id="getopt.examples-2">
+    <title><function>getopt</function> Example#2</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$shortopts  = "";
+$shortopts .= "f:";  // Required value
+$shortopts .= "v::"; // Optional value
+$shortopts .= "abc"; // These options do not accept values
+
+$longopts  = array(
+    "required:",     // Required value
+    "optional::",    // Optional value
+    "option",        // No value
+    "opt",           // No value
+);
+$options = getopt($shortopts, $longopts);
+var_dump($options);
+?>
+]]>
+    </programlisting>
+    <para>
+     Running the above script with <literal>php script.php -f "value for f" -v
+     -a --required value --optional="optional value" --option</literal>
+     will output:
+    </para>
+    <screen>
+<![CDATA[
+array(6) {
+  ["f"]=>
+  string(11) "value for f"
+  ["v"]=>
+  bool(false)
+  ["a"]=>
+  bool(false)
+  ["required"]=>
+  string(5) "value"
+  ["optional"]=>
+  string(14) "optional value"
+  ["option"]=>
+  bool(false)
+}
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example xml:id="getopt.examples-3">
+    <title><function>getopt</function> Example#3</title>
+    <para>Passing multiple options as one</para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$options = getopt("abc");
+var_dump($options);
+?>
+]]>
+    </programlisting>
+    <para>
+     Running the above script with <literal>php script.php -aaac</literal>
+     will output:
+    </para>
+    <screen>
+<![CDATA[
+array(2) {
+  ["a"]=>
+  array(3) {
+    [0]=>
+    bool(false)
+    [1]=>
+    bool(false)
+    [2]=>
+    bool(false)
+  }
+  ["c"]=>
+  bool(false)
+}
+]]>
+    </screen>
    </example>
   </para>
  </refsect1>
 
-<!--
  <refsect1 role="notes">
   &reftitle.notes;
+  <note>
+   <para>
+    The <link linkend="ini.register-argc-argv">register_argc_argv</link>
+    option must be enabled for this function to work
+   </para>
+  </note>
  </refsect1>
--->
 
 </refentry>