From 545654d60719161bdde4633afa42704cd5fedde5 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Mon, 19 Mar 2012 00:06:48 -0400
Subject: explain where things might go in reality and explain gt example
 Windows convention

---
 docs/conventions.rst  | 27 ++++++++++++++++++++++++---
 docs/narr/project.rst | 22 ++++++++++++++++++----
 2 files changed, 42 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/conventions.rst b/docs/conventions.rst
index 9e8510e4d..0c38e11d8 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -50,9 +50,30 @@ Code and configuration file blocks are presented in the following style:
      def foo(abc):
          pass
 
-When a command that should be typed on one line is too long to fit on
-a page, the backslash ``\`` is used to indicate that the following
-printed line should actually be part of the command:
+Example blocks representing UNIX shell commands are prefixed with a ``$``
+character, e.g.:
+
+  .. code-block:: text
+
+     $ ../bin/nosetests
+
+Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
+drive letter and/or a directory name, e.g.:
+
+  .. code-block:: text
+
+     c:\examples> ..\Scripts\nosetests
+
+Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
+example block commands are prefixed only with a ``>`` character, e.g.:
+
+  .. code-block:: text
+
+     > ..\Scripts\nosetests
+
+When a command that should be typed on one line is too long to fit on a page,
+the backslash ``\`` is used to indicate that the following printed line
+should actually be part of the command:
 
   .. code-block:: text
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 0134f4c74..ba5eee03a 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -68,10 +68,13 @@ Creating the Project
 
 In :ref:`installing_chapter`, you created a virtual Python environment via
 the ``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use
-the ``pcreate`` command installed within the virtualenv.  In
-:ref:`installing_chapter` we called the virtualenv directory ``env``; the
-following command assumes that our current working directory is that
-directory.  We'll choose the ``starter`` scaffold for this purpose.
+the ``pcreate`` command installed within the virtualenv.  We'll choose the
+``starter`` scaffold for this purpose.  When we invoke ``pcreate``, it will
+create a directory that represents our project.
+
+In :ref:`installing_chapter` we called the virtualenv directory ``env``; the
+following commands assume that our current working directory is the ``env``
+directory.
 
 On UNIX:
 
@@ -132,6 +135,17 @@ The ``MyProject`` project directory contains an additional subdirectory named
 :term:`package` which holds very simple :app:`Pyramid` sample code.  This is
 where you'll edit your application's Python code and templates.
 
+We created this project within an ``env`` virtualenv directory.  However,
+note that this is not mandatory.  The project directory can go more or less
+anywhere on your filesystem.  You don't need to put it in a special "web
+server" directory, and you don't need to put it within a virtualenv
+directory.  The author uses Linux mainly, and tends to put project
+directories which he creates within his ``~/projects`` directory.  On
+Windows, it's a good idea to put project directories within a directory that
+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:: 
 
    You’ll need to avoid using ``pcreate`` to create a project with the same
-- 
cgit v1.2.3