bjori Mon Feb 5 20:19:25 2007 UTC
Modified files:
/phpdoc/en/features commandline.xml
Log:
Improve markup
http://cvs.php.net/viewvc.cgi/phpdoc/en/features/commandline.xml?r1=1.41&r2=1.42&diff_format=u
Index: phpdoc/en/features/commandline.xml
diff -u phpdoc/en/features/commandline.xml:1.41
phpdoc/en/features/commandline.xml:1.42
--- phpdoc/en/features/commandline.xml:1.41 Mon Sep 5 09:33:41 2005
+++ phpdoc/en/features/commandline.xml Mon Feb 5 20:19:25 2007
@@ -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 @@
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 @@
?>
]]>
</programlisting>
- </para>
<para>
When using the <literal>CGI</literal> version, the output is:
+ </para>
<screen>
<![CDATA[
$ pwd
@@ -316,11 +318,13 @@
/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 @@
/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 @@
<para>
Telling PHP to execute a certain file.
</para>
- <para>
+ <example>
<screen>
<![CDATA[
php my_script.php
@@ -398,6 +403,8 @@
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 @@
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 @@
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 @@
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 @@
}
]]>
</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 @@
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 @@
?>
]]>
</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 @@
}
]]>
</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 @@
<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/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 @@
]]>
</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 @@
string(15) "doesntmakesense"
]]>
</screen>
- </para>
+ </example>
</entry>
</row>
<row>
@@ -704,9 +728,11 @@
<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 @@
[Zend Modules]
]]>
</screen>
- </para>
+ </example>
</entry>
</row>
<row>
@@ -745,27 +771,35 @@
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 @@
[...]
]]>
</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 @@
<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 @@
<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 @@
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies
]]>
</screen>
- </para>
+ </example>
</entry>
</row>
<row>
