diff --git a/features/commandline.xml b/features/commandline.xml
index 7016f7a792..5eb897cf72 100644
--- a/features/commandline.xml
+++ b/features/commandline.xml
@@ -366,29 +366,10 @@ Usage: php [options] [-f] <file> [--] [args...]
        <entry>--interactive</entry>
        <entry>
         <para>
-         Runs PHP interactively. If you compile PHP with the <link
-          linkend="ref.readline">Readline</link> extension (which is not
-         available on Windows), you'll have a nice shell, including a
-         completion feature (e.g. you can start typing a variable name, hit the
-         TAB key and PHP completes its name) and a typing history that can be
-         accessed using the arrow keys. The history is saved in the
-         <filename>~/.php_history</filename> file.
+         Runs PHP interactively. For more information, see the <link
+         linkend="features.commandline.interactive">Interactive shell</link>
+         section.
         </para>
-        <note>
-         <para>
-          Files included through <link
-          linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
-          linkend="ini.auto-append-file">auto_append_file</link> are parsed in
-          this mode but with some restrictions - e.g. functions have to be
-          defined before called.
-         </para>
-        </note>
-        <note>
-         <para>
-          <link linkend="language.oop5.autoload">Autoloading</link> is not
-          available if using PHP in &cli; interactive mode.
-         </para>
-        </note>
        </entry>
       </row>
       <row>
@@ -1389,6 +1370,159 @@ php -r 'fwrite(STDERR, "stderr\n");'
   </note>
  </section>
  <!--}}}-->
+
+ <!--Interactive shell: {{{-->
+ <section xml:id="features.commandline.interactive">
+  <title>Interactive shell</title>
+
+  <para>
+   As of PHP 5.1.0, the &cli.sapi; provides an interactive shell using the
+   <option>-a</option> option if PHP is compiled with the <option
+   role="configure">--with-readline</option> option.
+  </para>
+
+  <para>
+   Using the interactive shell you are able to type PHP code and have it
+   executed directly.
+  </para>
+
+  <example>
+   <title>Executing code using the interactive shell</title> 
+   <programlisting role="shell">
+<![CDATA[
+$ php -a
+Interactive shell
+
+php > echo 5+8;
+13
+php > function addTwo($n)
+php > {
+php { return $n + 2;
+php { }
+php > var_dump(addtwo(2));
+int(4)
+php > 
+]]>
+   </programlisting>
+  </example>
+
+  <para>
+   The interactive shell also features tab completion for functions,
+   constants, class names, variables, static method calls and class
+   constants.
+  </para>
+
+  <example>
+   <title>Tab completion</title>
+   <simpara>
+    Pressing the tab key twice when there are multiple possible completions
+    will result in a list of these completions:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > strp[TAB][TAB]
+strpbrk   strpos    strptime  
+php > strp
+]]>
+   </programlisting>
+   <simpara>
+    When there is only one possible completion, pressing tab once will
+    complete the rest on the same line:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > strpt[TAB]ime(
+]]>
+   </programlisting>
+   <simpara>
+    It is also possible doing completion on things that have been defined
+    during the interactive shell session:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > $fooThisIsAReallyLongVariableName = 42;
+php > $foo[TAB]ThisIsAReallyLongVariableName
+]]>
+   </programlisting>
+  </example>
+
+  <para>
+   The interactive shell stores your history and can be accessed using the up
+   and down keys. The history is saved in the
+   <filename>~/.php_history</filename> file.
+  </para>
+
+  <!-- NOT YET AVAILABLE, UNCOMMENT AND FIX VERSIONS WHEN RELEASED
+  <para>
+   As of [whatever becomes the next version], the &cli.sapi; provides
+   two new &php.ini; settings: <parameter>cli.pager</parameter> and
+   <parameter>cli.prompt</parameter>. The <parameter>cli.pager</parameter>
+   setting allows an external program (such as <filename>less</filename>) to
+   act as a pager for the output instead of being displayed directly on the
+   screen. The <parameter>cli.prompt</parameter> setting makes it possible to
+   change the <literal>php &gt;</literal> prompt.
+  </para>
+
+  <para>
+   In [whatever becoems the next version] it was also made possible setting
+   &php.ini; settings in the interactive shell using a shorthand notation.
+  </para>
+
+  <example>
+   <title>Setting &php.ini; settings in the interactive shell</title>
+   <simpara>
+    The <parameter>cli.prompt</parameter> setting:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > #cli.prompt=hello world :> 
+hello world :> 
+]]>
+   </programlisting>
+   <simpara>
+    Using backticks it is possible to have PHP code executed in the prompt:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > #cli.prompt=`echo date('H:i:s');` php > 
+15:49:35 php > echo 'hi';
+hi
+15:49:43 php > sleep(2);
+15:49:45 php > 
+]]>
+   </programlisting>
+   <simpara>
+    Setting the pager to <filename>less</filename>:
+   </simpara>
+   <programlisting role="shell">
+<![CDATA[
+php > #cli.pager=less
+php > phpinfo();
+(output displayed in less)
+php > 
+]]>
+   </programlisting>
+  </example>
+  -->
+
+  <note>
+   <para>
+    Files included through <link
+    linkend="ini.auto-prepend-file">auto_prepend_file</link> and <link
+    linkend="ini.auto-append-file">auto_append_file</link> are parsed in
+    this mode but with some restrictions - e.g. functions have to be
+    defined before called.
+   </para>
+  </note>
+
+  <note>
+   <para>
+    <link linkend="language.oop5.autoload">Autoloading</link> is not
+    available if using PHP in &cli; interactive mode.
+   </para>
+  </note>
+ </section>
+ <!--}}}-->
  
 </chapter>
 
@@ -1408,7 +1542,7 @@ sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
-vim600: syn=xml fen fdm=syntax fdl=2 si
+vim600: syn=xml fen fdm=marker fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->