derek Thu Jan 20 03:42:56 2005 EDT
Modified files:
/phpdoc/en/language basic-syntax.xml
Log:
restructured the docbook elements to follow
<this>
<that>
<the other>
Rewrote the sections, which were redundant, and added a few more
examples.
http://cvs.php.net/diff.php/phpdoc/en/language/basic-syntax.xml?r1=1.39&r2=1.40&ty=u
Index: phpdoc/en/language/basic-syntax.xml
diff -u phpdoc/en/language/basic-syntax.xml:1.39
phpdoc/en/language/basic-syntax.xml:1.40
--- phpdoc/en/language/basic-syntax.xml:1.39 Tue Jan 11 08:43:09 2005
+++ phpdoc/en/language/basic-syntax.xml Thu Jan 20 03:42:54 2005
@@ -1,85 +1,76 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.39 $ -->
+<!-- $Revision: 1.40 $ -->
<chapter id="language.basic-syntax">
<title>Basic syntax</title>
-
- <!--
-
- NOTE: Last modified: 2001-05-16 13:00 GMT
-
- the language part is currently under heavy revision. Please do not
- not make any heavy (i.e. structural) modifications to this part
- for a moment.
-
- You'd also better not start any translation yet.
-
- Comments are always welcome at [email protected]
-
- Progress:
-
- intro : DOESN'T EXIST - yet?
- new chapter, with some introductionary remarks?
- Will be discussed on the ML soon.
- basic-syntax:
- FINISHED
- except maybe moving the 'advanced escaping'
- to a better place?
- TODO:
- - nada
- types : Being revised. Added all new types
- Boolean and Integer are more or less finished.
- The rest isn't.
- TODO:
- - why is $foo[bar] bad syntax?
- - what's the difference between unset($bla) and
- $bla = NULL; (it is different!)
- - $obj->{expr} syntax
- - (unset) cast?????
- - $bla = unset <== should've been nuked, don't mention it
- - $str{offset} syntax, rather than $str[offset]
- - read notes and apply when any of them are useful
- - remove notes which have been included here.
- - ...
- the rest: Not yet started with.
- TODO:
- - ?
- oop : has been revised by Kristian, DONE.
- -->
-
<sect1 id="language.basic-syntax.phpmode">
<title>Escaping from HTML</title>
-
<para>
- When PHP parses a file, it simply passes the text of the file
- through until it encounters one of the special tags which tell it
- to start interpreting the text as PHP code. The parser then
- executes all the code it finds, up until it runs into a PHP
- closing tag, which tells the parser to just start passing the text
- through again. This is the mechanism which allows you to embed PHP
- code inside HTML: everything outside the PHP tags is left utterly
- alone, while everything inside is parsed as code.
+ When PHP parses a file, it looks for opening and closing tags,
+ which tell PHP to start and stop interpreting the code between
+ them. Parsing in this manner allows php to be embedded in all
+ sorts of different documents, as everything outside of a pair
+ of opening and closing tags is ignored by the PHP parser.
+ Most of the time you will see php embedded in HTML documents,
+ as in this example.
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<p>This is going to be ignored.</p>
+<?php echo 'While this is going to be parsed.'; ?>
+<p>This will also be ignored.</p>
+]]>
+ </programlisting>
+ </informalexample>
</para>
-
<para>
- There are four sets of tags which can be used to denote blocks of
- PHP code. Of these, only two (<?php. . .?> and <script
- language="php">. . .</script>) are always available; the
- others can be turned on or off from the
- &php.ini; configuration file. While the
- short-form tags and ASP-style tags may be convenient, they are not
- as portable as the longer versions. Also, if you intend to embed
- PHP code in XML or XHTML, you will need to use the
- <?php. . .?> form to conform to the XML.
+ You can also use more advanced structures:
+ <example>
+ <title>Advanced escaping</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+if ($expression) {
+ ?>
+ <strong>This is true.</strong>
+ <?php
+} else {
+ ?>
+ <strong>This is false.</strong>
+ <?php
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ This works as expected, because when PHP hits the ?> closing
+ tags, it simply starts outputting whatever it finds until it hits
+ another opening tag. The example given here is contrived, of
+ course, but for outputting large blocks of text, dropping out of
+ PHP parsing mode is generally more efficient than sending all of
+ the text through <function>echo</function> or
+ <function>print</function>.
</para>
-
<para>
- The tags supported by PHP are:
+ There are four different pairs of opening and closing tags
+ which can be used in php. Two of those, <?php ?> and
+ <script language="php"> </script>, are always available.
+ The other two are short tags and <productname>ASP</productname>
+ style tags, and can be turned on and off from the &php.ini;
+ configuration file. As such, while some people find short tags
+ and <productname>ASP</productname> style tags convenient, they
+ are less portable, and generally not recommended.
+ <note>
+ <para>
+ Also note that if you are embedding PHP within XML or XHTML
+ you will need to use the <?php ?> tags to remain
+ compliant with standards.
+ </para>
+ </note>
</para>
-
- <para>
- <example>
- <title>Ways of escaping from HTML</title>
- <programlisting role="php">
+ <para>
+ <example>
+ <title>PHP Opening and Closing Tags</title>
+ <programlisting role="php">
<![CDATA[
1. <?php echo("if you want to serve XHTML or XML documents, do like this\n");
?>
@@ -94,40 +85,37 @@
4. <% echo ("You may optionally use ASP-style tags"); %>
<%= $variable; # This is a shortcut for "<% echo . . ." %>
]]>
- </programlisting>
- </example>
- </para>
-
- <para>
- The first way, <?php. . .?>, is the preferred method, as it
- allows the use of PHP in XML-conformant code such as XHTML.
+ </programlisting>
+ </example>
</para>
-
<para>
- The second way is not available always. Short tags are available
- only when they have been enabled. This can be done via the
- <function>short_tags</function> function (PHP 3 only), by enabling
- the <link linkend="ini.short-open-tag">short_open_tag</link>
- configuration setting in the PHP config file, or by compiling PHP
- with the <option>--enable-short-tags</option> option to
- <command>configure</command>. Even if it is enabled by default in
- <filename>php.ini-dist</filename>, use of short tags are discouraged.
+ While the tags seen in examples one and two are both
+ always available, example one is the most commonly
+ used, and recommended, of the two.
</para>
-
<para>
- The third way is always available and safe like the first one. However,
- the first is the preferred and most used one.
- </para>
-
+ Short tags (example three) are only available when they are
+ enabled via the <link linkend="ini.short-open-tag">short_open_tag</link>
+ &php.ini; configuration file directive, or if php was configured
+ with the <option>--enable-short-tags</option> option.
+ <note>
+ <para>
+ If you are using PHP 3 you may also enable short tags via
+ the <function>short_tags</function> function. <emphasis>This
+ is only available in PHP 3!</emphasis>
+ </para>
+ </note>
+ </para>
<para>
- The fourth way is only available if <productname>ASP</productname>
- tags have been enabled using the <link
linkend="ini.asp-tags">asp_tags</link>
- configuration setting.
+ <productname>ASP</productname> style tags (example four) are only
available when
+ they are enabled via the <link linkend="ini.asp-tags">asp_tags</link>
&php.ini;
+ configuration file directive.
<note>
- <para>Support for <productname>ASP</productname> tags was added in
3.0.4.</para>
+ <para>
+ Support for <productname>ASP</productname> tags was added in 3.0.4.
+ </para>
</note>
</para>
-
<para>
<note>
<para>
@@ -139,56 +127,16 @@
</para>
</note>
</para>
-
- <para>
- The closing tag for the block will include the immediately
- trailing newline if one is present. Also, the closing tag
- automatically implies a semicolon; you do not need to have a
- semicolon terminating the last line of a PHP block.
- Closing tag of a PHP block at the end of a file is optional.
- </para>
-
- <para>
- PHP allows you to use structures like this:
- <example><title>Advanced escaping</title>
- <programlisting role="php">
-<![CDATA[
-<?php
-if ($expression) {
- ?>
- <strong>This is true.</strong>
- <?php
-} else {
- ?>
- <strong>This is false.</strong>
- <?php
-}
-?>
-]]>
- </programlisting>
- </example>
- This works as expected, because when PHP hits the ?> closing
- tags, it simply starts outputting whatever it finds until it hits
- another opening tag. The example given here is contrived, of
- course, but for outputting large blocks of text, dropping out of
- PHP parsing mode is generally more efficient than sending all of
- the text through <function>echo</function> or
- <function>print</function> or somesuch.
- </para>
</sect1>
-
<sect1 id="language.basic-syntax.instruction-separation">
<title>Instruction separation</title>
-
- <simpara>
- Instructions are separated the same as in C or Perl - terminate
- each statement with a semicolon.
- </simpara>
-
<para>
- The closing tag (?>) also implies the end of the statement, so
- the following are equivalent:
-
+ As in C or Perl, PHP requires instructions to be separated
+ with a semicolon at the end of each statement. The closing tag
+ of a block of PHP code automatically implies a semicolon; you
+ do not need to have a semicolon terminating the last line of a
+ PHP block. The closing tag for the block will include the immediately
+ trailing newline if one is present.
<informalexample>
<programlisting role="php">
<![CDATA[
@@ -200,14 +148,19 @@
]]>
</programlisting>
</informalexample>
- </para>
+ <note>
+ <para>
+ The closing tag of a PHP block at the end of a file is optional,
+ and in some cases is helpful when using output buffering and
+ <function>include</function> or <function>require</function>.
+ </para>
+ </note>
+ </para>
</sect1>
-
<sect1 id="language.basic-syntax.comments">
- <title>Comments</title>
-
+ <title>Comments</title>
<para>
- PHP supports 'C', 'C++' and Unix shell-style comments. For example:
+ PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For
example:
<informalexample>
<programlisting role="php">
@@ -223,11 +176,14 @@
</programlisting>
</informalexample>
</para>
-
<simpara>
- The "one-line" comment styles actually only comment to the end of
- the line or the current block of PHP code, whichever comes
- first.
+ The "one-line" comment styles only comment to the end of
+ the line or the current block of PHP code, whichever comes first.
+ This means that HTML code after <literal>// ?></literal> WILL be
printed:
+ ?> skips out of the PHP mode and returns to HTML mode, and
+ <literal>//</literal> cannot influence that.
+ If <link linkend="ini.asp-tags">asp_tags</link> configuration directive
+ is enabled, it behaves the same with <literal>// %></literal>.
</simpara>
<para>
<informalexample>
@@ -239,13 +195,11 @@
</programlisting>
</informalexample>
</para>
-
<simpara>
'C' style comments end by the first encountered <literal>*/</literal>.
You should be careful not to nest 'C' style comments, which can
happen when commenting out large blocks.
</simpara>
-
<para>
<informalexample>
<programlisting role="php">
@@ -259,16 +213,6 @@
</programlisting>
</informalexample>
</para>
-
- <simpara>
- The one-line comment styles actually only comment to the end
- of the line or the current block of PHP code, whichever comes first.
- This means that HTML code after <literal>// ?></literal> WILL be
printed:
- ?> skips out of the PHP mode and returns to HTML mode, and
- <literal>//</literal> cannot influence that.
- If <link linkend="ini.asp-tags">asp_tags</link> configuration directive
- is enabled, it behaves the same with <literal>// %></literal>.
- </simpara>
</sect1>
</chapter>
