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

Index: phpdoc-si/language/basic-syntax.xml
diff -u phpdoc-si/language/basic-syntax.xml:1.1.1.1 phpdoc-si/language/basic-syntax.xml:1.2
--- phpdoc-si/language/basic-syntax.xml:1.1.1.1	Sun Jul 28 15:12:12 2002
+++ phpdoc-si/language/basic-syntax.xml	Sun Jul 28 20:29:50 2002
@@ -1,9 +1,8 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1.1.1 $ -->
-<!-- EN-Revision: 1.27 Maintainer: spheroid Status: ready -->
-
+<?xml version="1.0" encoding="iso-8859-2"?>
+<!-- $Revision: 1.2 $ -->
+<!-- EN-Revision: 1.33 Maintainer: black Status: pending -->
  <chapter id="language.basic-syntax">
-  <title>Syntaksi</title>
+  <title>Basic syntax</title>
 
    <!--
    
@@ -49,134 +48,148 @@
    -->
    
   <sect1 id="language.basic-syntax.phpmode">
-   <title>PHP:n sisällyttäminen HTML-dokumenttiin</title>
+   <title>Escaping from HTML</title>
   
    <para>
-    Jäsentäessään tiedostoa PHP yksinkertaisesti ohittaa kaiken sisällön siihen
-    asti, kunnes se löytää erityisen aloitustagin, joka kertoo jäsentimelle 
-    aloittaa koodin PHP-tulkkaus. Sitten tulkki suorittaa kaiken koodin jonka 
-    löytää, aina PHP-lopputagiin asti. Tämän jälkeen tulkki aloittaa tekstin 
-    ohittamisen uudelleen. Tämä mekanismi antaa mahdollisuuden lisätä 
-    PHP-koodia HTML:n sisään: kaikki PHP-tagin ulkopuolella jätetään täysin 
-    rauhaan, kun taas kaikki muu tulkataan PHP-koodina.
+    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.
    </para>
 
    <para>
-    PHP:ssa on neljä tagiparia, joita voidaan käyttää koodin erottelemiseen.
-    Näistä kaksi (&lt;?php. . .?&gt; ja &lt;script language="php"&gt;. . .&lt;/script&gt;)
-    toimivat aina; muut voidaan ottaa käyttöön tai pois käytöstä &php.ini;
-    asetustiedostossa. Vaikka lyhyempimuotoiset ja ASP-tyyliset tagit voivat
-    olla käteviä, niitä tulisi välttää varsinkin jos haluaa koodinsa toimivan
-    asetuksista riippumatta. Jos aikomuksena on sisällyttää PHP-koodia XML- tai
-    XHTML-dokumenteissa, täytyy käyttää &lt;?php. . .?&gt; muotoa.
+    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>
-    PHP:n tukemat tagit ovat:
+    The tags supported by PHP are:
    </para>
 
     <para>
      <example>
-      <title>Tapoja erotella koodi HTML:stä</title>
+      <title>Ways of escaping from HTML</title>
       <programlisting role="php">
 <![CDATA[
-1.  <? echo ("tämä on yksinkertaisin SGML-merkintätapa\n"); ?>
-    <?= lauseke ?> Tämä on helpompi tapa ilmaista "<? echo lauseke ?>"
-    
-2.  <?php echo("XHTML- ja XML-dokumenttien kanssa voidaan käyttää seuraavaa menetelmää\n"); ?>
+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 ("jotkut editorit (kuten FrontPage) eivät pidä tällaisesta merkintätavasta");
+        echo ("some editors (like FrontPage) don't
+              like processing instructions");
     </script>
 
-4.  <% echo ("ASP-tagejä voidaan myös vaihtoehtoisesti käyttää"); %>
-    <%= $muuttuja; # Tämä on helpompi tapa ilmaista "<% echo . . ." %>
+4.  <% echo ("You may optionally use ASP-style tags"); %>
+    <%= $variable; # This is a shortcut for "<% echo . . ." %>
 ]]>
       </programlisting>
      </example>
     </para>
 
    <para>
-    Ensimmäinen vaihtoehto on käytettävissä ainoastaan, jos lyhyet
-    tagit ovat sallittu. Ne voidaan sallia funktion
-    <function>short_tags</function> avulla (PHP3 ainoastaan),
-    muuttamalla <link linkend="ini.short-open-tag">
-    short_open_tag</link> asetusta PHP:n konfiguraatiotiedostossa,
-    tai kääntämällä PHP --enable-short-tags -parametrillä
-    <command>configure</command> komennon kanssa.
+    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>
-    Huomautettakoon, että toisena listattu merkintätapa on yleisesti
-    suositeltu, koska se mahdollistaa PHP:n käytön XML:ää
-    noudattavan koodin, kuten XHTML:n kanssa.
+    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>
-    Neljäs vaihtoehto on käytettävissä ainoastaan, jos ASP-tyyliset
-    tagit ovat sallittu konfiguraatiotiedoston <link
-    linkend="ini.asp-tags">asp_tags</link> asetuksella.
+    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>ASP-tyylisten tagien tuki on lisätty versiossa 3.0.4.</para>
+     <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>
-    Lohkon lopetustagi sisältää heti seuraavana tulevan rivinvaihdoin,
-    mikäli sellainen vain on. Näin ollen tarvitaan kaksi rivinvaihtoa,
-    jos lopulliseen tulosteeseen halutaan rivinvaihto lopetustagin
-    jälkeen. Lopetustagi sisältää myös puolipisteen; PHP-lohkon
-    viimeisellä rivillä ei näin ollen tarvitse olla rivin lopettavaa
-    puolipistettä.
+    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 mahdollistaa seuraavanlaisten rakenteiden käytön:
-    <example><title>Kehittyneempää erottelemista</title>
+    PHP allows you to use structures like this:
+    <example><title>Advanced escaping</title>
      <programlisting role="php">
 <![CDATA[
 <?php
-if ($lauseke) { 
+if ($expression) { 
     ?>
-    <strong>Tämä on tosi</strong>
+    <strong>This is true.</strong>
     <?php 
 } else { 
     ?>
-    <strong>Tämä on epätosi.</strong>
+    <strong>This is false.</strong>
     <?php 
 }
 ?>
 ]]>
      </programlisting>
     </example>
-    Tämä toimii oletetulla tavalla, koska PHP yksinkertaisesti
-    tulostaa kaiken lopetustagin ?&gt; jälkeisen sisällön, kunnes
-    löytää uuden aloitustagin. Suurempien tekstimäärien tulostamiseen
-    tämä on tehokkaampi tapa kuin tulostaa <function>echo</function>,
-    <function>print</function> tai muilla vastaavilla menetelmillä.
+    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>Lausekkeiden erottelu</title>
+   <title>Instruction separation</title>
    
    <simpara>
-    Lausekkeet erotellaan samalla tavalla kuten C:ssä tai Perlissä
-    - jokainen lauseke päätetään puolipisteeseen.</simpara>
+    Instructions are separated the same as in C or Perl - terminate
+    each statement with a semicolon.</simpara>
 
    <para>
-    Lopetustagi (?&gt;) lopettaa myös lausekkeen, joten seuraavilla lausekkeilla
-    on täysin sama merkitys:
+    The closing tag (?&gt;) also implies the end of the statement, so
+    the following are equivalent:
 
     <informalexample>
      <programlisting role="php">
 <![CDATA[
 <?php
-    echo "Tämä on koe";
+    echo "This is a test";
 ?>
 
-<?php echo "Tämä on koe" ?>
+<?php echo "This is a test" ?>
 ]]>
      </programlisting>
     </informalexample>
@@ -184,20 +197,20 @@
   </sect1>
 
   <sect1 id="language.basic-syntax.comments">
-   <title>Kommentointi</title>
+   <title>Comments</title>
    
    <para>
-    PHP tukee 'C', 'C++' ja Unix shell-tyylisiä kommentointitapoja. Esimerkiksi:
+    PHP supports 'C', 'C++' and Unix shell-style comments. For example:
 
     <informalexample>
      <programlisting role="php">
 <![CDATA[
 <?php
-    echo "Tämä on koe"; // Tämä on yksirivinen C++-tyylinen kommentti
-    /* Tämä on monirivinen kommentti
-       ja tässä vielä yksi kommentti */
-    echo "Tämä on toinen koe";
-    echo "Vielä viimeinen koe"; # Tämä on Unix shell-tyylinen kommentti
+    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>
@@ -205,23 +218,22 @@
    </para>
 
    <simpara>
-    "Yksiriviset" kommentointityylit tosiasiassa kommentoivat
-    ainoastaan rivin tai PHP-lohkon loppuun, kumpi ensin sattuu
-    tulemaan.
+    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>Tämä on <?php # echo "yksinkertainen";?> esimerkki.</h1>
-<p>Ylläoleva otsikko tulostaa ruudulle 'Tämä on esimerkki'.
+<h1>This is an <?php # echo "simple";?> example.</h1>
+<p>The header above will say 'This is an example'.
 ]]>
     </programlisting>
    </informalexample> 
 
    <simpara>
-    Kannattaa olla tarkkana, että koodiin ei synny sisäkkäisiä
-    'C'-tyylisiä kommentteja. Näin voi käydä kommentoitaessa
-    pidempiä koodinpätkiä.
+    You should be careful not to nest 'C' style comments, which can
+    happen when commenting out large blocks.
    </simpara>
 
    <informalexample>
@@ -229,12 +241,19 @@
 <![CDATA[
 <?php
  /* 
-    echo "Tämä on testi"; /* Tämä kommentti tulee aiheuttamaan virheen */
+    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>