cvs: phpdoc /en/language basic-syntax.xml
| From: | Derek Ford | Date: | Thu, 20 Jan 2005 08:42:56 +0000 |
| Subject: | cvs: phpdoc /en/language basic-syntax.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969366066@lists.php.net to get a copy of this message | ||
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 phpdoc@lists.php.net - - 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>
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 phpdoc@lists.php.net - - 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>