Merge pull request #1265 from jim-parry/release/prep2

WIP Fix docs re PHP server

Author: jim-parry

user_guide_src/source/installation/index.rst

@@ -54,6 +54,9 @@ By default, the application will run using the "production" environment. To
 take advantage of the debugging tools provided, you should set the environment
 to "develop".
 
+.. caution:: Using PHP's built-in web server is likely to cause problems,
+	as it does not process the `.htaccess` file used to properly handle requests.
+
 That's it!
 
 If you're new to CodeIgniter, please read the :doc:`Getting

user_guide_src/source/installation/troubleshooting.rst

@@ -28,3 +28,12 @@ do this open your *application/Config/App.php* file and change this::
 To this::
 
 	public $indexPage = 'index.php?';
+
+The tutorial gives 404 errors everywhere :(
+-------------------------------------------
+
+You can't follow the tutorial using PHP's built-in web server.
+It doesn't process the `.htaccess` file needed to route
+requests properly.
+
+The solution: use Apache to server your site.

user_guide_src/source/tutorial/static_pages.rst

@@ -134,21 +134,60 @@ view.
 	match the case of the actual directory and file itself or the system will
 	throw errors on case-sensitive platforms.
 
+Running the App
+---------------
+
+Ready to test? You cannot run the app using PHP's built-in server,
+since it will not properly process the ``.htaccess`` rules that are provided in 
+``public``, and which eliminate the need to specify "index.php/"
+as part of a URL. CodeIgniter has its own command that you can use though.
+
+From the command line, at the root of your project:
+
+    php spark serve
+
+will start a web server, accessible on port 8080. If you set the location field
+in your browser to ``localhost:8080``, you should see the CodeIgniter welcome page.
+
+You can now try several URLs in the browser location field, to see what the `Pages`
+controller you made above produces...
+
+- ``localhost:8080/pages`` will show the results from the `index` method
+  inside our `Pages` controller, which is to display the CodeIgniter "welcome" page,
+  because "index" is the default controller method
+- ``localhost:8080/pages/index`` will also show the CodeIgniter "welcome" page,
+  because we explicitly asked for the "index" methid
+- ``localhost:8080/pages/view`` will show the "home" page that you made above,
+  because it is the default "page" parameter to the `view()` method.
+- ``localhost:8080/pages/view/home`` will also show the "home" page that you made above,
+  because we explicitly asked for it
+- ``localhost:8080/pages/view/about`` will show the "about" page that you made above,
+  because we explicitly asked for it
+- ``localhost:8080/pages/view/shop`` will show a "404 - File Not Found" error page,
+  because there is no `application/Views/pages/shop.php`
+
+
 Routing
 -------
 
-The controller is now functioning! Point your browser to
-``[your-site-url]index.php/pages/view`` to see your page. When you visit
-``index.php/pages/view/about`` you'll see the about page, again including
-the header and footer.
+The controller is now functioning! 
 
 Using custom routing rules, you have the power to map any URI to any
 controller and method, and break free from the normal convention:
 ``http://example.com/[controller-class]/[controller-method]/[arguments]``
 
 Let's do that. Open the routing file located at
-*application/Config/Routes.php* and add the following two lines.
-Remove all other code that adds any element in the ``$route`` items.
+*application/Config/Routes.php* and look for the "Route Definitions"
+section of the configuration file.
+
+The only uncommented line there to start with should be:::
+
+    $routes->add('/', 'Home::index');
+
+This directive says that any incoming request without any content
+specified should be handled by the ``index`` method inside the ``Home`` controller.
+
+Add the following two lines, in front of the route directive for '/'.
 
 ::