cvs: phpdoc-sk /language basic-syntax.xml

Index: phpdoc-sk/language/basic-syntax.xml
+++ phpdoc-sk/language/basic-syntax.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
 <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>Vyskoèenie z HTML</title>
  
   <para>
    Keï PHP analyzuje súbor, jednoducho prechádza testom v súbore pokia¾
    sa nevyskytne jedna zo špeciálnych znaèiek, ktorá oznaèuje zaèiatok
    interpretácie textu ako PHP kód. Analyzátor potom spúša všetok kód,
    ktorý nájde až pokia¾ nepríde k uzatváracej znaèke PHP, ktorá povie 
    analyzátoru, že má zasa prechádza text. Tento mechanizmus dovo¾uje
    vloži PHP kód dovnútra HTML: všetko mimo PHP znaèiek je ignorované,
    pokia¾ všetko vo vnútri je analyzované ako kód.
   </para>

   <para>
    There are four sets of tags which can be used to denote blocks of
    PHP code. Of these, only two (&lt;?php. . .?&gt; and &lt;script
    language="php"&gt;. . .&lt;/script&gt;) 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
    &lt;?php. . .?&gt; form to conform to the XML.
   </para>

   <para>
    The tags supported by PHP are:
   </para>

    <para>
     <example>
      <title>Ways of escaping from HTML</title>
      <programlisting role="php">
<![CDATA[
1.  <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?>

2.  <? echo ("this is the simplest, an SGML processing instruction\n"); ?>
    <?= expression ?> This is a shortcut for "<? echo expression ?>"
    
3.  <script language="php">
        echo ("some editors (like FrontPage) don't
              like processing instructions");
    </script>

4.  <% echo ("You may optionally use ASP-style tags"); %>
    <%= $variable; # This is a shortcut for "<% echo . . ." %>
]]>
      </programlisting>
     </example>
    </para>

   <para>
    The first way, &lt;?php. . .?&gt;, is the preferred method, as it
    allows the use of PHP in XML-conformant code such as XHTML.
   </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 --enable-short-tags option to
    <command>configure</command>. Even if it is enabled by default in
    php.ini-dist, use of short tags are discouraged.
   </para>

   <para>
    The fourth way is only available if ASP-style tags have been
    enabled using the <link linkend="ini.asp-tags">asp_tags</link>
    configuration setting.

    <note>
     <para>Support for ASP-style tags was added in 3.0.4.</para>
    </note>
   </para>

   <note>
    <para>
     Using short tags should be avoided when developing applications
     or libraries that are meant for redistribution, or deployment on
     PHP servers which are not under your control, because short tags
     may not be supported on the target server.  For portable,
     redistributable code, be sure not to use short tags.
    </para>
   </note>

   <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.
   </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 ?&gt; 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 (?&gt;) also implies the end of the statement, so
    the following are equivalent:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
    echo "This is a test";
?>

<?php echo "This is a test" ?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="language.basic-syntax.comments">
   <title>Comments</title>
   
   <para>
    PHP supports 'C', 'C++' and Unix shell-style comments. For example:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
    echo "This is a test"; // This is a one-line c++ style comment
    /* This is a multi line comment
       yet another line of comment */
    echo "This is yet another test";
    echo "One Final Test"; # This is shell-style style comment
?>
]]>
     </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.
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<h1>This is an <?php # echo "simple";?> example.</h1>
<p>The header above will say 'This is an example'.
]]>
    </programlisting>
   </informalexample> 

   <simpara>
    You should be careful not to nest 'C' style comments, which can
    happen when commenting out large blocks.
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
 /* 
    echo "This is a test"; /* This comment will cause a problem */
 */
?>
]]>
    </programlisting>
   </informalexample>
   
   <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 // ?> WILL be printed: ?> skips out of
    the PHP mode and returns to HTML mode, and // cannot influence that.
   </simpara>
  </sect1>
 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->