Fix grammar in control structures (#5750)

Author: kamil-tekiela

language/control-structures/do-while.xml

@@ -7,13 +7,13 @@
  <simpara>
   <literal>do-while</literal> loops are very similar to
   <literal>while</literal> loops, except the truth expression is
-  checked at the end of each iteration instead of in the beginning.
+  checked at the end of each iteration instead of at the beginning.
   The main difference from regular <literal>while</literal> loops is
   that the first iteration of a <literal>do-while</literal> loop is
   guaranteed to run (the truth expression is only checked at the end
   of the iteration), whereas it may not necessarily run with a
   regular <literal>while</literal> loop (the truth expression is
-  checked at the beginning of each iteration, if it evaluates to
+  checked at the beginning of each iteration; if it evaluates to
   &false; right from the beginning, the loop
   execution would end immediately).
  </simpara>
@@ -40,7 +40,7 @@ do {
  </para>
  <simpara>
    The above loop would run one time exactly, since after the first
-   iteration, when truth expression is checked, it evaluates to
+   iteration, when the truth expression is checked, it evaluates to
    &false; (<varname>$i</varname> is not bigger than 0) and the loop
    execution ends.
  </simpara>

language/control-structures/elseif.xml

@@ -46,7 +46,7 @@ a is equal to b
   <literal>elseif</literal> expression (if any) that evaluates to
   &true; would be executed.  In PHP, it's possible to write
   <literal>else if</literal> (in two words) and the behavior would be identical
-  to the one of <literal>elseif</literal> (in a single word).  The syntactic meaning
+  to that of <literal>elseif</literal> (in a single word).  The syntactic meaning
   is slightly different (the same behavior as C) but the bottom line
   is that both would result in exactly the same behavior.
  </simpara>

language/control-structures/for.xml

@@ -23,7 +23,7 @@ for (expr1; expr2; expr3)
   loop.
  </simpara>
  <simpara>
-  In the beginning of each iteration,
+  At the beginning of each iteration,
   <varname>expr2</varname> is evaluated.  If it evaluates to
   &true;, the loop continues and the nested
   statement(s) are executed.  If it evaluates to
@@ -124,7 +124,7 @@ for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i . " ", $i++);
  <simpara>
   Of course, the first example appears to be the nicest one (or
   perhaps the fourth), but you may find that being able to use empty
-  expressions in <literal>for</literal> loops comes in handy in many
+  expressions in <literal>for</literal> loops comes in handy on many
   occasions.
  </simpara>
  <para>
@@ -142,7 +142,7 @@ endfor;
   </informalexample>
  </para>
  <simpara>
-  It's a common thing to many users to iterate through arrays like in the
+  It's common for many users to iterate through arrays like in the
   example below.
  </simpara>
  <para>

language/control-structures/foreach.xml

@@ -143,7 +143,7 @@ Dynamic arrays:
     <simpara>
      Please note that
      <link linkend="language.types.array.syntax.destructuring">array destructuring</link>
-     via <literal>[]</literal> is only possible as of PHP 7.1.0
+     via <literal>[]</literal> is only possible as of PHP 7.1.0.
     </simpara>
    </note>
   </para>
@@ -291,9 +291,9 @@ array(4) {
   </para>
   <warning>
    <simpara>
-    Reference to a <literal>$value</literal> of the last array element
-    remain even after the <literal>foreach</literal> loop. It is recommended
-    to destroy these using <function>unset</function>.
+    A reference to the <literal>$value</literal> of the last array element
+    remains even after the <literal>foreach</literal> loop. It is recommended
+    to destroy it using <function>unset</function>.
     Otherwise, the following behavior will occur:
    </simpara>
    <informalexample>

language/control-structures/include-once.xml

@@ -4,14 +4,14 @@
 <sect1 xml:id="function.include-once" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>include_once</title>
  <?phpdoc print-version-for="include_once"?>
- <para>
+ <simpara>
   The <literal>include_once</literal> expression includes and evaluates
   the specified file during the execution of the script.
-  This is a behavior similar to the <function>include</function> expression,
+  This behavior is similar to the <function>include</function> expression,
   with the only difference being that if the code from a file has already
   been included, it will not be included again, and include_once returns &true;.  As the name suggests,
   the file will be included just once.
- </para>
+ </simpara>
  <para>
   <literal>include_once</literal> may be used in cases where
   the same file might be included and evaluated more than once during a

language/control-structures/include.xml

@@ -83,7 +83,7 @@ echo "A $color $fruit"; // A green apple
   then all of the code contained in the called file will behave as
   though it had been defined inside that function.  So, it will follow
   the variable scope of that function.
-  An exception to this rule are <link
+  An exception to this rule is <link
   linkend="language.constants.magic">magic constants</link> which are
   evaluated by the parser before the include occurs.
  </simpara>
@@ -161,15 +161,15 @@ include 'http://www.example.com/file.php?foo=1&bar=2';
  </para>
  <warning>
   <title>Security warning</title>
-  <para>
-   Remote file may be processed at the remote server (depending on the file
-   extension and the fact if the remote server runs PHP or not) but it still
+  <simpara>
+   A remote file may be processed at the remote server (depending on the file
+   extension and whether or not the remote server runs PHP) but it still
    has to produce a valid PHP script because it will be processed at the
    local server. If the file from the remote server should be processed
-   there and outputted only, <function>readfile</function> is much better
+   there and outputted only, <function>readfile</function> is a much better
    function to use. Otherwise, special care should be taken to secure the
    remote script to produce a valid and desired code.
-  </para>
+  </simpara>
  </warning>
  <para>
   See also <link linkend="features.remote-files">Remote files</link>,
@@ -194,7 +194,7 @@ include 'http://www.example.com/file.php?foo=1&bar=2';
  <para>
   Because <literal>include</literal> is a special language construct,
   parentheses are not needed around its argument. Take care when comparing
-  return value.
+  the return value.
   <example>
    <title>Comparing return value of include</title>
    <programlisting role="php" annotations="non-interactive">
@@ -257,15 +257,15 @@ echo $bar; // prints 1
   If the file can't be included, &false; is returned and
   <constant>E_WARNING</constant> is issued.
  </simpara>
- <para>
+ <simpara>
   If there are functions defined in the included file, they can be used in the
-  main file independent if they are before <function>return</function> or after.
+  main file regardless of whether they are before <function>return</function> or after.
   If the file is included twice, PHP will raise a fatal error because the
   functions were already declared.
   It is recommended to use <function>include_once</function> instead of
-  checking if the file was already included and conditionally return inside
+  checking if the file was already included and conditionally returning inside
   the included file.
- </para>
+ </simpara>
  <simpara>
   Another way to "include" a PHP file into a variable is to capture the
   output by using the <link linkend="ref.outcontrol">Output Control

language/control-structures/match.xml

@@ -86,7 +86,7 @@ string(8) "Teenager"
   <note>
    <simpara>
     When a <literal>match</literal> expression is used as a standalone
-    expression it <emphasis>must</emphasis> be terminated
+    expression, it <emphasis>must</emphasis> be terminated
     by a semicolon <literal>;</literal>.
    </simpara>
   </note>
@@ -110,7 +110,7 @@ string(8) "Teenager"
    </listitem>
    <listitem>
     <simpara>
-     <literal>match</literal> arms do not fall-through to later cases the way
+     <literal>match</literal> arms do not fall through to later cases the way
      <literal>switch</literal> statements do.
     </simpara>
    </listitem>
@@ -123,7 +123,7 @@ string(8) "Teenager"
  </para>
 
  <para>
-  As <literal>switch</literal> statements, <literal>match</literal>
+  Like <literal>switch</literal> statements, <literal>match</literal>
   expressions are executed match arm by match arm.
   In the beginning, no code is executed.
   The conditional expressions are only evaluated if all previous conditional
@@ -146,11 +146,11 @@ $result = match ($x) {
   </informalexample>
  </para>
 
- <para>
+ <simpara>
   <literal>match</literal> expression arms may contain multiple expressions
-  separated by a comma.  That is a logical OR, and is a short-hand for multiple
+  separated by a comma.  That is a logical OR, and is a shorthand for multiple
   match arms with the same right-hand side.
- </para>
+ </simpara>
  <para>
   <informalexample>
    <programlisting role="php" annotations="non-interactive">
@@ -186,17 +186,17 @@ $expressionResult = match ($condition) {
   </informalexample>
   <note>
    <simpara>
-    Multiple default patterns will raise a
+    Multiple default patterns will raise an
     <constant>E_FATAL_ERROR</constant> error.
    </simpara>
   </note>
  </para>
 
- <para>
+ <simpara>
   A <literal>match</literal> expression must be exhaustive.  If the
-  subject expression is not handled by any match arm an
+  subject expression is not handled by any match arm, an
   <classname>UnhandledMatchError</classname> is thrown.
- </para>
+ </simpara>
 
  <example>
   <title>Example of an unhandled match expression</title>
@@ -240,15 +240,15 @@ object(UnhandledMatchError)#1 (7) {
  </example>
 
  <sect2>
-  <title>Using match expressions to handle non identity checks</title>
+  <title>Using match expressions to handle non-identity checks</title>
   <para>
    It is possible to use a <literal>match</literal> expression to handle
    non-identity conditional cases by using <code>true</code> as the subject
    expression.
   </para>
 
   <example>
-   <title>Using a generalized match expressions to branch on integer ranges</title>
+   <title>Using a generalized match expression to branch on integer ranges</title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -273,7 +273,7 @@ string(11) "young adult"
   </example>
 
   <example>
-   <title>Using a generalized match expressions to branch on string content</title>
+   <title>Using a generalized match expression to branch on string content</title>
    <programlisting role="php">
 <![CDATA[
 <?php

language/control-structures/switch.xml

@@ -6,26 +6,26 @@
  <?phpdoc print-version-for="switch"?>
  <simpara>
   The <literal>switch</literal> statement is similar to a series of
-  IF statements on the same expression.  In many occasions, you may
-  want to compare the same variable (or expression) with many
+  <literal>if</literal> statements on the same expression. In situations where
+  it is necessary to compare the same variable or expression with many
   different values, and execute a different piece of code depending
-  on which value it equals to.  This is exactly what the
-  <literal>switch</literal> statement is for.
+  on which value it equals, the <literal>switch</literal> statement is often
+  more convenient and easier to read.
  </simpara>
  <note>
   <simpara>
    Note that unlike some other languages, the
    <link linkend="control-structures.continue">continue</link> statement
-   applies to <literal>switch</literal> and acts similar to <literal>break</literal>.  If you
+   applies to <literal>switch</literal> and acts similarly to <literal>break</literal>.  If you
    have a <literal>switch</literal> inside a loop and wish to continue to the next iteration of
    the outer loop, use <literal>continue 2</literal>.
   </simpara>
  </note>
  <note>
-  <para>
-   Note that switch/case does
+  <simpara>
+   Note that switch/case does a
    <link linkend="types.comparisions-loose">loose comparison</link>.
-  </para>
+  </simpara>
  </note>
 
  <para>
@@ -126,7 +126,7 @@ i equals 2
   evaluated only once and the result is compared to each
   <literal>case</literal> statement. In an <literal>elseif</literal>
   statement, the condition is evaluated again. If your condition is
-  more complicated than a simple compare and/or is in a tight loop,
+  more complicated than a simple comparison and/or is in a tight loop,
   a <literal>switch</literal> may be faster.
  </simpara>
  <para>
@@ -190,7 +190,7 @@ i is not equal to 0, 1 or 2
   </informalexample>
   <note>
    <simpara>
-    Multiple default cases will raise a
+    Multiple default cases will raise an
     <constant>E_COMPILE_ERROR</constant> error.
    </simpara>
   </note>
@@ -244,7 +244,8 @@ B
  </para>
  <para>
   For more complex comparisons, the value &true; may be used as the switch value.
-  Or, alternatively, <literal>if</literal>-<literal>else</literal> blocks instead of <literal>switch</literal>.
+  Or, alternatively, <literal>if</literal>-<literal>else</literal> blocks
+  can be used instead of <literal>switch</literal>.
   <informalexample>
    <programlisting role="php">
 <![CDATA[