[DOCUMENTATION] English: manual fixes

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@19809 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/tutorials/multiuser-authentication.xml

@@ -1,26 +1,28 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
 <sect1 id="learning.multiuser.authentication">
-    <title>Authenticating Users in ZF</title>
+    <title>Authenticating Users in Zend Framework</title>
 
     <sect2 id="learning.multiuser.authentication.intro">
         <title>Introduction to Authentication</title>
 
         <para>
-            Once a web application has been able to distinguish one user from another by establishing a
-            session, web applications typically want to validate the identity of a user.  The process
-            of validating a consumer as being authentic is "authentication."  Authentication is made up
-            of two distinctive parts: an identity and a set of credentials.  It takes some variation of
-            both presented to the application for processing so that it may authenticate a user.
+            Once a web application has been able to distinguish one user from another by
+            establishing a session, web applications typically want to validate the identity
+            of a user. The process of validating a consumer as being authentic is "authentication."
+            Authentication is made up of two distinctive parts: an identity and a set of
+            credentials. It takes some variation of both presented to the application for
+            processing so that it may authenticate a user.
         </para>
 
         <para>
-            While the most common pattern of authentication revolves around usernames and passwords,
-            it should be stated that this is not always the case.  Identities are not limited to
-            usernames.  In fact, any public identifier can be used: an assigned number, social security
-            number, or residence address.  Likewise, credentials are not limited to passwords.
-            Credentials can come in the form of protected private information: fingerprint, eye retinal
-            scan, passphrase, or any other obscure personal information.
+            While the most common pattern of authentication revolves around usernames and
+            passwords, it should be stated that this is not always the case. Identities are
+            not limited to usernames. In fact, any public identifier can be used: an assigned
+            number, social security number, or residence address. Likewise, credentials are not
+            limited to passwords. Credentials can come in the form of protected private
+            information: fingerprint, eye retinal scan, passphrase, or any other obscure personal
+            information.
         </para>
 
     </sect2>
@@ -29,19 +31,21 @@
         <title>Basic Usage of Zend_Auth</title>
 
         <para>
-            In the following example, we will be using Zend_Auth to complete what is probably the most
-            prolific form of authentication: username and password from a database table.  This
-            example assumes that you have already setup your application using Zend_Application, and
-            that inside that application you have configured a database connection.
+            In the following example, we will be using <classname>Zend_Auth</classname> to
+            complete what is probably the most prolific form of authentication: username and
+            password from a database table. This example assumes that you have already setup your
+            application using <classname>Zend_Application</classname>, and that inside that
+            application you have configured a database connection.
         </para>
 
         <para>
-            The job of the Zend_Auth class is twofold.  First, it should be able to accept an
-            authentication adapter to use to authenticate a user.  Secondly, after a successful
-            authentication of a user, it should persist throughout each and every request that might
-            need to know if the current user has indeed been authenticated.  To persist this data,
-            Zend_Auth consumes Zend_Session_Namespace, but you will generally never need to interact
-            with this session object.
+            The job of the <classname>Zend_Auth</classname> class is twofold. First, it should
+            be able to accept an authentication adapter to use to authenticate a user. Secondly,
+            after a successful authentication of a user, it should persist throughout each and
+            every request that might need to know if the current user has indeed been
+            authenticated. To persist this data, <classname>Zend_Auth</classname> consumes
+            <classname>Zend_Session_Namespace</classname>, but you will generally never need
+            to interact with this session object.
         </para>
 
         <para>
@@ -60,16 +64,16 @@ CREATE TABLE users (
 
         <para>
             The above demonstrates a user table that includes a username, password, and also a
-            password salt column.  This salt column is used as part of a technique called salting that
-            would improve the security of your database of information against brute force attacks
-            targeting the algorithm of your password hashing.
-            <ulink url="http://en.wikipedia.org/wiki/Salting_%28cryptography%29">More information</ulink>
-            on salting.
+            password salt column. This salt column is used as part of a technique called salting
+            that would improve the security of your database of information against brute force
+            attacks targeting the algorithm of your password hashing. <ulink
+                url="http://en.wikipedia.org/wiki/Salting_%28cryptography%29">More
+                information</ulink> on salting.
         </para>
 
         <para>
-            For this implementation, we must first make a simple form that we can utilized as the
-            "login form".  We will use Zend_Form to accomplish this.
+            For this implementation, we must first make a simple form that we can utilized as
+            the "login form". We will use <classname>Zend_Form</classname> to accomplish this.
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -104,10 +108,12 @@ class Default_Form_Auth_Login extends Zend_Form
 
         <para>
             With the above form, we can now go about creating our login action for
-            our authentication controller.  This controller will be called "AuthController", and
-            will be located at application/controllers/AuthController.php.  It will have a single
-            method called "loginAction" which will serve as the self-posting action.  In other words,
-            regardless of the url was POSTed to or GETed to, this method will handle the logic.
+            our authentication controller. This controller will be called
+            "<classname>AuthController</classname>", and will be located at
+            <filename>application/controllers/AuthController.php</filename>. It will have a
+            single method called "<methodname>loginAction()</methodname>" which will serve as the
+            self-posting action. In other words, regardless of the url was POSTed to or GETed
+            to, this method will handle the logic.
         </para>
 
         <para>
@@ -156,9 +162,9 @@ class AuthController extends Zend_Controller_Action
 ]]></programlisting>
 
         <para>
-            The corresponding view script is quite simple for this action.  It will set the current
-            url since this form is self processing, and it will display the form.  This view script is
-            located at application/views/scripts/auth/login.phtml:
+            The corresponding view script is quite simple for this action. It will set the current
+            url since this form is self processing, and it will display the form. This view script
+            is located at <filename>application/views/scripts/auth/login.phtml</filename>:
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -167,12 +173,11 @@ echo $this->form;
 ]]></programlisting>
 
         <para>
-            There you have it.  With these basics you can expand the general concepts to include
-            more complex authentication scenarios.  For more information on other Zend_Auth adapters,
-            have a look in <link linkend="zend.auth">the reference guide</link>.
+            There you have it. With these basics you can expand the general concepts to include
+            more complex authentication scenarios. For more information on other
+            <classname>Zend_Auth</classname> adapters, have a look in
+            <link linkend="zend.auth">the reference guide</link>.
         </para>
-
     </sect2>
-
 </sect1>
 

documentation/manual/en/tutorials/multiuser-authorization.xml

@@ -1,17 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
 <sect1 id="learning.multiuser.authorization">
-    <title>Building an Authorization System in ZF</title>
+    <title>Building an Authorization System in Zend Framework</title>
 
     <sect2 id="learning.multiuser.authorization.intro">
         <title>Introduction to Authorization</title>
 
         <para>
             After a user has been identified as being authentic, an application can go about its
-            business of providing some useful and desirable resources to a consumer.  In many cases,
+            business of providing some useful and desirable resources to a consumer. In many cases,
             applications might contain different resource types, with some resources having stricter
-            rules regarding access.  This process of determining who has access to which resources is
-            the process of "authorization".  Authorization in its simplest form is the composition of
+            rules regarding access. This process of determining who has access to which resources is
+            the process of "authorization". Authorization in its simplest form is the composition of
             these elements:
         </para>
 
@@ -36,8 +36,9 @@
         </itemizedlist>
 
         <para>
-            In ZF, the Zend_Acl component handles the task of building a tree of roles, resources and
-            privileges to manage and query authorization requests against.
+            In Zend Framework, the <classname>Zend_Acl</classname> component handles the task of
+            building a tree of roles, resources and privileges to manage and query authorization
+            requests against.
         </para>
 
     </sect2>
@@ -48,19 +49,22 @@
 <!-- explain the interaction with a User object, how -->
 
         <para>
-            When using Zend_Acl, any models can serve as roles or resources by simply implementing
-            the proper interface.  To be used in a role capacity, the class must implement the
-            Zend_Acl_Role_Interface, which requires only getRoleId().  To be used in a resource
-            capacity, a class must implement the Zend_Acl_Resource_Interface which similarly requires
-            the class implement the getResourceId() method.
+            When using <classname>Zend_Acl</classname>, any models can serve as roles or resources
+            by simply implementing the proper interface. To be used in a role capacity, the class
+            must implement the <classname>Zend_Acl</classname>, which requires only
+            <methodname>getRoleId()</methodname>. To be used in a resource capacity, a class must
+            implement the <classname>Zend_Acl_Resource_Interface</classname> which similarly
+            requires the class implement the <methodname>getResourceId()</methodname> method.
         </para>
 
         <para>
-            Demonstrated below is a simple user model.  This model can take part in our ACL system
-            simply by implementing the Zend_Acl_Role_Interface.  The method getRoleId() will return
-            the id "guest" when an ID is not known, or it will return the role ID that was assigned
-            to this actual user object.  This value can effectively come from anywhere, a static definition
-            or perhaps dynamically from the users database role itself.
+            Demonstrated below is a simple user model. This model can take part in our
+            <acronym>ACL</acronym> system simply by implementing the
+            <classname>Zend_Acl_Role_Interface</classname>. The method
+            <methodname>getRoleId()</methodname> will return the id "guest" when an ID is not known,
+            or it will return the role ID that was assigned to this actual user object. This value
+            can effectively come from anywhere, a static definition or perhaps dynamically from the
+            users database role itself.
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -80,12 +84,12 @@ class Default_Model_User implements Zend_Acl_Role_Interface
 ]]></programlisting>
 
         <para>
-            While the concept of a user as a role is pretty straight forward, your application might
-            choose to have any other models in your system as a potential "resource" to be consumed in
-            this ACL system.  For simplicity, we'll use the example of a blog post.  Since the type of
-            the resource is tied to the type of the object, this class will only return 'blogPost' as
-            the resource ID in this system.  Naturally, this value can be dynamic if your system requires
-            it to be so.
+            While the concept of a user as a role is pretty straight forward, your application
+            might choose to have any other models in your system as a potential "resource" to be
+            consumed in this <acronym>ACL</acronym> system. For simplicity, we'll use the example
+            of a blog post. Since the type of the resource is tied to the type of the object,
+            this class will only return 'blogPost' as the resource ID in this system. Naturally,
+            this value can be dynamic if your system requires it to be so.
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -99,9 +103,10 @@ class Default_Model_BlogPost implements Zend_Acl_Resource_Interface
 ]]></programlisting>
 
         <para>
-            Now that we have at least a role and a resource, we can go about defining the rules of the
-            ACL system.  These rules will be consulted when the system receives a query about what is
-            possible given a certain role, resources, and optionally a privilege.
+            Now that we have at least a role and a resource, we can go about defining the rules
+            of the <acronym>ACL</acronym> system. These rules will be consulted when the system
+            receives a query about what is possible given a certain role, resources, and optionally
+            a privilege.
         </para>
 
         <para>
@@ -113,7 +118,8 @@ $acl = new Zend_Acl();
 
 // setup the various roles in our system
 $acl->addRole('guest');
-$acl->addRole('owner', 'guest');  // owner inherits all of the rules of guest
+// owner inherits all of the rules of guest
+$acl->addRole('owner', 'guest');
 
 // add the resources
 $acl->addResource('blogPost');
@@ -125,13 +131,15 @@ $acl->allow('owner', 'blogPost', 'publish');
 ]]></programlisting>
 
         <para>
-            The above rules are quite simple: a guest role and an owner role exist; as does a blogPost
-            type resource.  Guests are allowed to view blog posts, and owners are allowed to post and publish
-            blog posts.  To query this system one might do any of the following:
+            The above rules are quite simple: a guest role and an owner role exist; as does a
+            blogPost type resource. Guests are allowed to view blog posts, and owners are
+            allowed to post and publish blog posts. To query this system one might do any of
+            the following:
         </para>
 
         <programlisting language="php"><![CDATA[
-$guestUser = new Default_Model_User(); // assume the user model is of type guest resource
+// assume the user model is of type guest resource
+$guestUser = new Default_Model_User();
 $ownerUser = new Default_Model_Owner('OwnersUsername');
 
 $post = new Default_Model_BlogPost();
@@ -143,20 +151,21 @@ $acl->isAllowed($ownerUser, $post, 'post'); // true
 ]]></programlisting>
 
         <para>
-            As you can see, the above rules exercise whether owners and guests can view posts, which
-            they can, or post new posts, which owners can and guests cannot.  But as you might expect
-            this type of system might not be as dynamic as we wish it to be.  What if we want to ensure
-            a specific owner actual owns a very specific blog post before allowing him to publish it?
-            In other words, we want to ensure that only post owners have the ability to publish their
-            own posts.
+            As you can see, the above rules exercise whether owners and guests can view posts,
+            which they can, or post new posts, which owners can and guests cannot. But as you
+            might expect this type of system might not be as dynamic as we wish it to be.
+            What if we want to ensure a specific owner actual owns a very specific blog post
+            before allowing him to publish it? In other words, we want to ensure that only post
+            owners have the ability to publish their own posts.
         </para>
 
         <para>
-            This is where assertions come in.  Assertions are methods that will be called out to
-            when the static rule checking is simply not enough.  When registering an assertion object
-            this object will be consulted to determine, typically dynamically, if some roles has access
-            to some resource, with some optional privlidge that can only be answered by the logic within
-            the assertion.  For this example, we'll use the following assertion:
+            This is where assertions come in. Assertions are methods that will be called out to
+            when the static rule checking is simply not enough. When registering an assertion
+            object this object will be consulted to determine, typically dynamically, if some
+            roles has access to some resource, with some optional privlidge that can only be
+            answered by the logic within the assertion. For this example, we'll use the following
+            assertion:
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -171,14 +180,25 @@ class OwnerCanPublishBlogPostAssertion implements Zend_Acl_Assert_Interface
      * @param $privilege
      * @return bool
      */
-    public function assert(Zend_Acl $acl, Zend_Acl_Role_Interface $user = null, Zend_Acl_Resource_Interface $blogPost = null, $privilege = null)
+    public function assert(Zend_Acl $acl,
+                           Zend_Acl_Role_Interface $user = null,
+                           Zend_Acl_Resource_Interface $blogPost = null,
+                           $privilege = null)
     {
         if (!$user instanceof Default_Model_User) {
-            throw new Exception(__CLASS__ . '::' . __METHOD__ . ' expects the role to be an instance of User');
+            throw new Exception(__CLASS__
+                              . '::'
+                              . __METHOD__
+                              . ' expects the role to be'
+                              . ' an instance of User');
         }
 
         if (!$blogPost instanceof Default_Model_BlogPost) {
-            throw new Exception(__CLASS__ . '::' . __METHOD__ . ' expects the resource to be an instance of BlogPost');
+            throw new Exception(__CLASS__
+                              . '::'
+                              . __METHOD__
+                              . ' expects the resource to be'
+                              . ' an instance of BlogPost');
         }
 
         // if role is publisher, he can always modify a post
@@ -194,33 +214,32 @@ class OwnerCanPublishBlogPostAssertion implements Zend_Acl_Assert_Interface
         }
     }
 }
-
 ]]></programlisting>
 
         <para>
-            To hook this into our ACL system, we would do the following:
+            To hook this into our <acronym>ACL</acronym> system, we would do the following:
         </para>
 
         <programlisting language="php"><![CDATA[
 // replace this:
 //   $acl->allow('owner', 'blogPost', 'publish');
 // with this:
-$acl->allow('owner', 'blogPost', 'publish', new OwnerCanPublishBlogPostAssertion());
+$acl->allow('owner',
+            'blogPost',
+            'publish',
+            new OwnerCanPublishBlogPostAssertion());
 
 // lets also add the role of a "publisher" who has access to everything
 $acl->allow('publisher', 'blogPost', 'publish');
-
 ]]></programlisting>
 
         <para>
-            Now, anytime the ACL is consulted about whether or not an owner can publish a specific
-            blog post, this assertion will be run.  This assertion will ensure that unless the role
-            type is 'publisher' the owner role must be logically tied to the blog post in question.
-            In this example, we check to see that the ownerUserId property of the blog post matches
-            the id of the owner passed in.
+            Now, anytime the <acronym>ACL</acronym> is consulted about whether or not an owner
+            can publish a specific blog post, this assertion will be run. This assertion will
+            ensure that unless the role type is 'publisher' the owner role must be logically
+            tied to the blog post in question. In this example, we check to see that the
+            <property>ownerUserId</property> property of the blog post matches the id of the
+            owner passed in.
         </para>
-
-
     </sect2>
-
 </sect1>

documentation/manual/en/tutorials/multiuser-intro.xml

@@ -1,26 +1,28 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
 <sect1 id="learning.multiuser.intro">
-    <title>Building Multi-User Applications With ZF</title>
+    <title>Building Multi-User Applications With Zend Framework</title>
 
     <sect2 id="learning.multiuser.intro.zf">
         <title>Zend Framework</title>
 
         <para>
-            When the original "web" was created, it was designed to be a publishing platform for
-            predominantly static content.  As demand for content on the web grew, as did the number of
-            consumers on the internet for web content, the demand for using the web as an application
-            platform also grew.  Since the web is inherently good at delivering a simultaneous
-            experience to many consumers from a single location, it makes it an ideal environment for
-            building dynamically driven, multi-user, and more commonly today, social systems.
+            When the original "web" was created, it was designed to be a publishing platform
+            for predominantly static content. As demand for content on the web grew, as did
+            the number of consumers on the internet for web content, the demand for using the
+            web as an application platform also grew. Since the web is inherently good at
+            delivering a simultaneous experience to many consumers from a single location,
+            it makes it an ideal environment for building dynamically driven, multi-user,
+            and more commonly today, social systems.
         </para>
 
         <para>
-            HTTP is the protocol of the web: a stateless, typically short lived, request/response
-            protocol.  This protocol was designed this way because the original intent of the web was
-            to serve or publish static content.  It is this very design that has made the web as
-            immensely successful as it is.  It is also exactly this design that brings new concerns to
-            developers who wish to use the web as an application platform.
+            <acronym>HTTP</acronym> is the protocol of the web: a stateless, typically short
+            lived, request and response protocol. This protocol was designed this way because
+            the original intent of the web was to serve or publish static content. It is this
+            very design that has made the web as immensely successful as it is. It is also
+            exactly this design that brings new concerns to developers who wish to use the
+            web as an application platform.
         </para>
 
         <para>
@@ -51,10 +53,11 @@
             <title>Consumer Vs. User</title>
 
             <para>
-                Notice we use the term "consumer" instead of person.  Increasingly, web applications
-                are becoming service driven.  This means that not only are real people ("users") with
-                real web browsers consuming and using your application, but also other web applications
-                through machine service technologies such as ReST, SOAP, and XML-RPC.  In this respect,
+                Notice we use the term "consumer" instead of person. Increasingly, web applications
+                are becoming service driven. This means that not only are real people ("users") with
+                real web browsers consuming and using your application, but also other web
+                applications through machine service technologies such as <acronym>REST</acronym>,
+                <acronym>SOAP</acronym>, and <acronym>XML-RPC</acronym>. In this respect,
                 people, as well as other consuming applications, should all be treated in same with
                 regard to the concerns outlined above.
             </para>
@@ -63,8 +66,9 @@
 
         <para>
             In the following chapters, we'll take a look at these common problems relating to
-            authentication and authorization in detail.  We will discover how 3 main components:
-            Zend_Session, Zend_Auth, and Zend_Acl; provide an out-of-the-box solution as well as the
+            authentication and authorization in detail. We will discover how 3 main components:
+            <classname>Zend_Session</classname>, <classname>Zend_Auth</classname>, and
+            <classname>Zend_Acl</classname>; provide an out-of-the-box solution as well as the
             extension points each have that will cater to a more customized solution.
         </para>
     </sect2>