Merge remote-tracking branch 'upstream/master' into doc_render

Doing something to make the pull request have the right stuff.

5 files changed, 49 insertions, 34 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index fb67b899b..e419a8b20 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -25,6 +25,10 @@ on :term:`PyPy` (1.9+).
 :app:`Pyramid` installation does not require the compilation of any C code, so
 you need only a Python interpreter that meets the requirements mentioned.
 
+Some :app:`Pyramid` dependencies may attempt to build C extensions for
+performance speedups. If a compiler or Python headers are unavailable the
+dependency will fall back to using pure Python instead.
+
 For Mac OS X Users
 ~~~~~~~~~~~~~~~~~~
 
@@ -285,13 +289,20 @@ Installing :app:`Pyramid` Into the Virtual Python Environment
 After you've got your virtualenv installed, you may install :app:`Pyramid`
 itself using the following commands:
 
-.. code-block:: text
-
-   $ $VENV/bin/easy_install pyramid
+.. parsed-literal::
+      
+   $ $VENV/bin/easy_install "pyramid==\ |release|\ "
 
 The ``easy_install`` command will take longer than the previous ones to
 complete, as it downloads and installs a number of dependencies.
 
+.. note::
+
+   If you see any warnings and/or errors related to failing to compile the C
+   extensions, in most cases you may safely ignore those errors. If you wish
+   to use the C extensions, please verify that you have a functioning compiler
+   and the Python header files installed.
+
 .. index::
    single: installing on Windows
 
@@ -357,9 +368,9 @@ You can use Pyramid on Windows under Python 2 or 3.
 #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
    installed:
 
-   .. code-block:: text
-
-      c:\env> %VENV%\Scripts\easy_install pyramid
+   .. parsed-literal::
+      
+      c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
 
 What Gets Installed
 -------------------
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 359fb31d3..9a1ba190d 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -144,7 +144,7 @@ contains no space characters, so it's wise to *avoid* a path that contains
 i.e. ``My Documents``.  As a result, the author, when he uses Windows, just
 puts his projects in ``C:\projects``.
 
-.. warning:: 
+.. warning::
 
    You’ll need to avoid using ``pcreate`` to create a project with the same
    name as a Python standard library component. In particular, this means you
@@ -972,12 +972,15 @@ named ``views`` instead of within a single ``views.py`` file, you might:
 - Create a ``views`` directory inside your ``myproject`` package directory
   (the same directory which holds ``views.py``).
 
-- *Move* the existing ``views.py`` file to a file inside the new ``views``
-  directory named, say, ``blog.py``.
+- Create a file within the new ``views`` directory named ``__init__.py``.  (It
+  can be empty.  This just tells Python that the ``views`` directory is a
+  *package*.)
 
-- Create a file within the new ``views`` directory named ``__init__.py`` (it
-  can be empty, this just tells Python that the ``views`` directory is a
-  *package*.
+- *Move* the existing ``views.py`` file to a file inside the new ``views``
+  directory named, say, ``blog.py``.  Because the ``templates`` directory
+  remains in the ``myproject`` package, the template :term:`asset
+  specification`s in ``blog.py`` must now be fully qualified with the
+  project's package name (``myproject:templates/blog.pt``).
 
 You can then continue to add view callable functions to the ``blog.py``
 module, but you can also add other ``.py`` files which contain view callable
@@ -1026,7 +1029,7 @@ server.  Waitress is a server that is suited for development and light
 production usage.  It's not the fastest nor the most featureful WSGI server.
 Instead, its main feature is that it works on all platforms that Pyramid
 needs to run on, making it a good choice as a default server from the
-perspective of Pyramid's developers.  
+perspective of Pyramid's developers.
 
 Any WSGI server is capable of running a :app:`Pyramid` application.  But we
 suggest you stick with the default server for development, and that you wait
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 434dbdad5..98584e608 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -17,26 +17,26 @@ Pyramid is a breeze. Unfortunately "standard" is not so simple in Python.
 For this Quick Tour, it means:
 `Python <http://www.python.org/download/releases/>`_, a
 `virtual environment <http://docs.python.org/dev/library/venv.html>`_
-(or `virtualenv for Python 2.7 <https://pypi.python.org/pypi/virtualenv>`_,
+(or `virtualenv for Python 2.7 <https://pypi.python.org/pypi/virtualenv>`_),
 and `setuptools <https://pypi.python.org/pypi/setuptools/>`_.
 
 As an example, for Python 3.3+ on Linux:
 
-.. code-block:: bash
+.. parsed-literal::
 
   $ pyvenv env33
   $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python
-  $ env33/bin/easy_install pyramid
+  $ env33/bin/easy_install "pyramid==\ |release|\ "
 
 For Windows:
 
-.. code-block:: posh
+.. parsed-literal::
 
     # Use your browser to download:
     #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-    c:\> c:\Python33\python -m venv env33
-    c:\> env33\Scripts\python ez_setup.py
-    c:\> env33\Scripts\easy_install pyramid
+    c:\\> c:\\Python33\\python -m venv env33
+    c:\\> env33\\Scripts\\python ez_setup.py
+    c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ "
 
 Of course Pyramid runs fine on Python 2.6+, as do the examples in this
 *Quick Tour*. We're just showing Python 3 a little love (Pyramid had
@@ -297,7 +297,7 @@ The only change in our view...point the renderer at the ``.jinja2`` file:
 Our Jinja2 template is very similar to our previous template:
 
 .. literalinclude:: quick_tour/jinja2/hello_world.jinja2
-    :language: jinja
+    :language: html
 
 Pyramid's templating add-ons register a new kind of renderer into your
 application. The renderer registration maps to different kinds of
diff --git a/docs/quick_tour/jinja2/hello_world.jinja2 b/docs/quick_tour/jinja2/hello_world.jinja2
index e177744b5..7a902dd3a 100644
--- a/docs/quick_tour/jinja2/hello_world.jinja2
+++ b/docs/quick_tour/jinja2/hello_world.jinja2
@@ -1,4 +1,5 @@
-<html xmlns="http://www.w3.org/1999/xhtml">
+<!DOCTYPE html>
+<html lang="en">
 <head>
     <title>Hello World</title>
 </head>
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index df63ff912..40e818807 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -94,23 +94,23 @@ and where our virtual environment will reside:
 
    Final directory structure.
 
-The commands to do so are as follows:
+For Linux, the commands to do so are as follows:
 
 .. code-block:: bash
 
     # Mac and Linux
     $ cd ~
-    $ mkdir projects
-    $ cd projects
-    $ mkdir quick_tutorial
-    $ cd quick_tutorial
+    $ mkdir -p projects/quick_tutorial
+    $ cd projects/quick_tutorial
+
+For Windows:
+
+.. code-block:: posh
 
     # Windows
     c:\> cd \
-    c:\> mkdir projects
-    c:\> cd projects
-    c:\> mkdir quick_tutorial
-    c:\> cd quick_tutorial
+    c:\> mkdir projects\quick_tutorial
+    c:\> cd projects\quick_tutorial
 
 In the above figure, your user home directory is represented by ``~``.  In
 your home directory, all of your projects are in the ``projects`` directory.
@@ -208,13 +208,13 @@ Install Pyramid
 We have our Python standard prerequisites out of the way. The Pyramid
 part is pretty easy:
 
-.. code-block:: bash
+.. parsed-literal::
 
     # Mac and Linux
-    $ $VENV/bin/easy_install pyramid
+    $ $VENV/bin/easy_install "pyramid==\ |release|\ "
 
     # Windows
-    c:\> %VENV%\Scripts\easy_install pyramid
+    c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
 
 Our Python virtual environment now has the Pyramid software available.