From 263d831c26664a2b11f3b21538b588b3786f7d03 Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Mon, 5 Feb 2007 20:19:25 +0000
Subject: [PATCH] Improve markup

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@229064 c90b9560-bf6c-de11-be94-00142212c4b1
---
 features/commandline.xml | 75 ++++++++++++++++++++++++++++++----------
 1 file changed, 57 insertions(+), 18 deletions(-)

diff --git a/features/commandline.xml b/features/commandline.xml
index d6f476a805..ba3831c4c7 100644
--- a/features/commandline.xml
+++ b/features/commandline.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.41 $ -->
+<!-- $Revision: 1.42 $ -->
 <chapter id="features.commandline">
  <title>Using PHP from the command line</title>
  <para>
@@ -294,8 +294,10 @@ php -r 'fwrite(STDERR, "stderr\n");'
      role="strong">not</emphasis> change the current directory to the directory
      of the executed script!
     </para>
+    <example>
     <para>
      Example showing the difference to the <literal>CGI SAPI</literal>:
+     </para>
      <programlisting role="php">
 <![CDATA[
 <?php
@@ -304,9 +306,9 @@ echo getcwd(), "\n";
 ?>
 ]]>
      </programlisting>
-    </para>
     <para>
      When using the <literal>CGI</literal> version, the output is:
+     </para>
      <screen>
 <![CDATA[
 $ pwd
@@ -316,11 +318,13 @@ $ php -q another_directory/test.php
 /tmp/another_directory
 ]]>
      </screen>
+     <para>
      This clearly shows that PHP changes its current
      directory to the one of the executed script.
     </para>
     <para>
      Using the <literal>CLI SAPI</literal> yields:
+     </para>
      <screen>
 <![CDATA[
 $ pwd
@@ -330,9 +334,10 @@ $ php -f another_directory/test.php
 /tmp
 ]]>
      </screen>
-     This allows greater flexibility when writing shell tools in
-     PHP.
+     <para>
+      This allows greater flexibility when writing shell tools in PHP.
     </para>
+    </example>
     <note>
      <para>
       The <literal>CGI SAPI</literal> supports this <literal>CLI SAPI</literal>
@@ -390,7 +395,7 @@ Usage: php [options] [-f] <file> [--] [args...]
     <para>
      Telling PHP to execute a certain file.
     </para>
-    <para>
+    <example>
      <screen>
 <![CDATA[
 php my_script.php
@@ -398,6 +403,8 @@ php my_script.php
 php -f my_script.php
 ]]>
      </screen>
+    </example>
+    <para>
      Both ways (whether using the <option>-f</option> switch or not) execute
      the file <filename>my_script.php</filename>. You can choose any file to
      execute - your PHP scripts do not have to end with the
@@ -410,12 +417,14 @@ php -f my_script.php
      Pass the PHP code to execute directly on the command
      line.
     </para>
-    <para>
+    <example>
      <screen>
 <![CDATA[
 php -r 'print_r(get_defined_constants());'
 ]]>
      </screen>
+    </example>
+    <para>
      Special care has to be taken in regards of shell variable substitution and
      quoting usage.
     </para>
@@ -436,12 +445,14 @@ php -r 'print_r(get_defined_constants());'
      This gives the powerful ability to dynamically create
      PHP code and feed it to the binary, as shown in this
      (fictional) example:
+    </para>
+    <example>
      <screen>
 <![CDATA[
 $ some_application | some_filter | php | sort -u >final_output.txt
 ]]>
      </screen>
-    </para>
+    </example>
    </listitem>
   </orderedlist>
   You cannot combine any of the three ways to execute code.
@@ -471,7 +482,7 @@ $ some_application | some_filter | php | sort -u >final_output.txt
    PHP, every argument following it is passed
    untouched to your script.
  </para>
- <para>
+ <example>
   <screen>
 <![CDATA[
 # This will not execute the given code but will show the PHP usage
@@ -489,7 +500,7 @@ array(2) {
 }
 ]]>
   </screen>
- </para>
+ </example>
  <para>
   However, there's another way of using PHP for shell
   scripting. You can write a script where the first line starts with
@@ -498,6 +509,9 @@ array(2) {
   starting and end tags. Once you have set the execution attributes of the file
   appropriately (e.g. <command>chmod +x test</command>) your script can be
   executed like a normal shell or perl script:
+ </para>
+ <example>
+  <title>Execute PHP script as shell script</title>
   <programlisting role="php">
 <![CDATA[
 #!/usr/bin/php
@@ -506,8 +520,10 @@ var_dump($argv);
 ?>
 ]]>
   </programlisting>
+  <para>
   Assuming this file is named <filename>test</filename> in the current
   directory, we can now do the following:
+  </para>
   <screen>
 <![CDATA[
 $ chmod +x test
@@ -524,6 +540,8 @@ array(4) {
 }
 ]]>
   </screen>
+ </example>
+ <para>
   As you see, in this case no care needs to be taken when passing parameters
   which start with <literal>-</literal> to your script.
  </para>
@@ -569,9 +587,11 @@ array(4) {
       <entry>--php-ini</entry>
       <entry>
        <para>
-        With this option one can either specify a directory where to look for
-        &php.ini; or you can specify a custom <literal>INI</literal> file
-        directly (which does not need to be named &php.ini;), e.g.:
+        This option can either specify a directory where to look for
+        &php.ini; or specify a custom <literal>INI</literal> file
+        (which does not need to be named &php.ini;), e.g.:
+       </para>
+       <example>
         <screen>
 <![CDATA[
 $ php -c /custom/directory/ my_script.php
@@ -579,6 +599,8 @@ $ php -c /custom/directory/ my_script.php
 $ php -c /custom/directory/custom-file.ini my_script.php
 ]]>
         </screen>
+       </example>
+       <para>
         If you don't specify this option, file is searched in
         <link linkend="configuration.file">default locations</link>.
        </para>
@@ -606,8 +628,10 @@ $ php -c /custom/directory/custom-file.ini my_script.php
 ]]>
         </screen>
        </para>
+       <example>
        <para>
         Examples (lines are wrapped for layout reasons):
+        </para>
         <screen>
 <![CDATA[
 # Omitting the value part will set the given configuration directive to "1"
@@ -630,7 +654,7 @@ $  php
 string(15) "doesntmakesense"
 ]]>
         </screen>
-       </para>
+       </example>
       </entry>
      </row>
      <row>
@@ -704,9 +728,11 @@ string(15) "doesntmakesense"
       <entry>-m</entry>
       <entry>--modules</entry>
       <entry>
+       <example>
        <para>
         Using this option, PHP prints out the built in (and loaded) PHP and
         Zend modules:
+        </para>
         <screen>
 <![CDATA[
 $ php -m
@@ -725,7 +751,7 @@ ctype
 [Zend Modules]
 ]]>
         </screen>
-       </para>
+       </example>
       </entry>
      </row>
      <row>
@@ -745,27 +771,35 @@ ctype
          to not collide with command line variable substitution done by the
          shell.
         </para>
+        <example>
         <para>
          Example showing a parser error
+         </para>
          <screen>
 <![CDATA[
 $ php -r "$foo = get_defined_constants();"
 Command line code(1) : Parse error - parse error, unexpected '='
 ]]>
          </screen>
+        </example>
+        <para>
          The problem here is that the sh/bash performs variable substitution
          even when using double quotes <literal>"</literal>. Since the
          variable <varname>$foo</varname> is unlikely to be defined, it
          expands to nothing which results in the code passed to
          PHP for execution actually reading:
+        </para>
+        <example>
          <screen>
 <![CDATA[
 $ php -r " = get_defined_constants();"
 ]]>
          </screen>
+         <para>
          The correct way would be to use single quotes <literal>'</literal>.
          Variables in single-quoted strings are not expanded
          by sh/bash.
+         </para>
          <screen>
 <![CDATA[
 $ php -r '$foo = get_defined_constants(); var_dump($foo);'
@@ -782,6 +816,8 @@ array(370) {
   [...]
 ]]>
          </screen>
+        </example>
+        <para>
          If you are using a shell different from sh/bash, you might experience
          further issues. Feel free to open a bug report at
          <ulink url="&url.php.bugs;">&url.php.bugs;</ulink>.
@@ -848,17 +884,18 @@ array(370) {
        <para>
         PHP code to execute after processing the input. Added in PHP 5.
        </para>
-       <para>
-        Example of using <option>-B</option>, <option>-R</option> and
+       <example>
+        <title>Using the <option>-B</option>, <option>-R</option> and
         <option>-E</option> options to count the number of lines of a
         project.
+        </title>
         <screen>
 <![CDATA[
 $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Total Lines: $l\n";'
 Total Lines: 37328
 ]]>
         </screen>
-       </para>
+       </example>
       </entry>
      </row>
      <row>
@@ -887,8 +924,10 @@ Total Lines: 37328
       <entry>-v</entry>
       <entry>--version</entry>
       <entry>
+       <example>
        <para>
         Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
+        </para>
         <screen>
 <![CDATA[
 $ php -v
@@ -896,7 +935,7 @@ PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
 Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies
 ]]>
         </screen>
-       </para>
+       </example>
       </entry>
      </row>
      <row>