grammar and markup

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@218051 c90b9560-bf6c-de11-be94-00142212c4b1

appendices/userlandnaming.xml

@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <appendix id="userlandnaming">
  <title>Userland Naming Guide</title>
  <para>
   The following is a guide for how to best choose names for identifiers
-  in PHP userland code. When choosing names for any code that creates symbols
-  in the global namespace it is important to take into account the following
-  guide lines to prevent future version of PHP to clash with userland code.
+  in userland PHP code. When choosing names for any code that creates symbols
+  in the global namespace, it is important to take into account the following
+  guidelines to prevent future versions of PHP from clashing with your
+  symbols.
  </para>
 
  <section id="userlandnaming.globalnamespace">
@@ -29,9 +30,9 @@
  <section id="userlandnaming.rules">
   <title>Rules</title>
   <para>
-   The following list gives an overview of what rights the PHP project
-   reserves itself when choosing names for new internal identifiers. Note
-   that the definitive guide is the official
+   The following list gives an overview of which rights the PHP project
+   reserves for itself, when choosing names for new internal identifiers.
+   The definitive guide is the official
    <ulink url="&url.userlandnaming.cs;">CODING STANDARDS</ulink>:
   </para>
 
@@ -52,8 +53,8 @@
    <listitem>
     <para>
      PHP will prefix any global symbols of an extension with the name of
-     the extension (note that in the past there have been numerous
-     exceptions to this rule). Examples:
+     the extension. (In the past, there have been numerous
+     exceptions to this rule.) Examples:
     </para>
 
     <itemizedlist>
@@ -71,19 +72,21 @@
    </listitem>
    <listitem>
     <para>
-     Iterators and Exceptions are however simply postfixed with "Iterator"
-     and "Exception". Examples:
+     Iterators and Exceptions are however simply postfixed with
+     "<literal>Iterator</literal>" and "<literal>Exception</literal>."
+     Examples:
     </para>
     <itemizedlist>
-     <listitem><para>ArrayIterator</para></listitem>
-     <listitem><para>LogicException</para></listitem>
+     <listitem><para><literal>ArrayIterator</literal></para></listitem>
+     <listitem><para><literal>LogicException</literal></para></listitem>
     </itemizedlist>
    </listitem>
    <listitem>
     <para>
-     PHP reserves all function names starting with __ as magical. It is
-     recommended that you do not use function names with __ in PHP unless
-     you want some documented magic functionality. Examples:
+     PHP reserves all symbols starting with <literal>__</literal>
+     as magical. It is recommended that you do not create symbols starting
+     with <literal>__</literal> in PHP unless
+     you want to use documented magical functionality. Examples:
     </para>
     <itemizedlist>
      <listitem><para><function>__get</function></para></listitem>
@@ -96,12 +99,12 @@
  <section id="userlandnaming.tips">
   <title>Tips</title>
   <para>
-   In order to write future proof code it is therefore recommended to prefix
-   (or postfix) anything that goes into the global namespace with a fairly
-   random 3-4 letter prefix (or postfix) separated with an underscore. It is
+   In order to write future-proof code, it is recommended that you prefix
+   (or suffix) anything that goes into the global namespace with an uncommon
+   3-4 letter prefix (or suffix) separated with an underscore. It is
    recommended that in order to prevent namespace clashes with other userland
-   code that projects research existing prefixes (or postfixes) used in other
-   projects and advertise their chosen prefix (or postfix) appropriately.
+   code that projects research existing prefixes (or suffixes) used in other
+   projects and advertise their chosen prefix (or suffix) appropriately.
    Examples:
   </para>