Merge branch 'master' into twophase

16 files changed, 107 insertions, 46 deletions

diff --git a/docs/_static/pyramid.png b/docs/_static/pylons.png
index 53f83e4d0..53f83e4d0 100644
--- a/docs/_static/pyramid.png
+++ b/docs/_static/pylons.png
diff --git a/docs/_static/pylons_small.png b/docs/_static/pylons_small.png
new file mode 100644
index 000000000..53f83e4d0
--- /dev/null
+++ b/docs/_static/pylons_small.png
diff --git a/docs/conf.py b/docs/conf.py
index e520c9d82..653f7ab15 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -128,11 +128,11 @@ html_theme = 'pylons'
 html_title = 'The Pyramid Web Application Development Framework v%s' % release
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = 'Home'
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
-#html_logo = '_static/pylons.png'
+html_logo = '_static/pyramid.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -201,7 +201,7 @@ latex_documents = [
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-latex_logo = '_static/pyramid.png'
+latex_logo = '_static/pylons_small.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py
index 580dfe546..936404c82 100644
--- a/docs/narr/MyProject/myproject/__init__.py
+++ b/docs/narr/MyProject/myproject/__init__.py
@@ -10,3 +10,4 @@ def main(global_config, **settings):
                     renderer='myproject:templates/mytemplate.pt')
     config.add_static_view('static', 'myproject:static')
     return config.make_wsgi_app()
+
diff --git a/docs/narr/MyProject/myproject/static/footerbg.png b/docs/narr/MyProject/myproject/static/footerbg.png
new file mode 100644
index 000000000..1fbc873da
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/footerbg.png
diff --git a/docs/narr/MyProject/myproject/static/headerbg.png b/docs/narr/MyProject/myproject/static/headerbg.png
new file mode 100644
index 000000000..0596f2020
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/headerbg.png
diff --git a/docs/narr/MyProject/myproject/static/ie6.css b/docs/narr/MyProject/myproject/static/ie6.css
new file mode 100644
index 000000000..b7c8493d8
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/ie6.css
@@ -0,0 +1,8 @@
+* html img,
+* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
+this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
+this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
+this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
+this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
+);}
+#wrap{display:table;height:100%}
diff --git a/docs/narr/MyProject/myproject/static/logo.png b/docs/narr/MyProject/myproject/static/logo.png
deleted file mode 100644
index 88f5d9865..000000000
--- a/docs/narr/MyProject/myproject/static/logo.png
+++ /dev/null
diff --git a/docs/narr/MyProject/myproject/static/middlebg.png b/docs/narr/MyProject/myproject/static/middlebg.png
new file mode 100644
index 000000000..2369cfb7d
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/middlebg.png
diff --git a/docs/narr/MyProject/myproject/static/pylons.css b/docs/narr/MyProject/myproject/static/pylons.css
index c153be07f..33b21ac1a 100644
--- a/docs/narr/MyProject/myproject/static/pylons.css
+++ b/docs/narr/MyProject/myproject/static/pylons.css
@@ -4,34 +4,23 @@ body{line-height:1;}
 ol,ul{list-style:none;}
 blockquote,q{quotes:none;}
 blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;}
-/* remember to define focus styles! */
 :focus{outline:0;}
-/* remember to highlight inserts somehow! */
 ins{text-decoration:none;}
 del{text-decoration:line-through;}
-/* tables still need 'cellspacing="0"' in the markup */
 table{border-collapse:collapse;border-spacing:0;}
-/* restyling */
 sub{vertical-align:sub;font-size:smaller;line-height:normal;}
 sup{vertical-align:super;font-size:smaller;line-height:normal;}
-/* lists */
 ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;}
 ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;}
 li{display:list-item;}
-/* nested lists have no top/bottom margins */
 ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;}
-/* 2 deep unordered lists use a circle */
 ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;}
-/* 3 deep (or more) unordered lists use a square */
 ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;}
 .hidden{display:none;}
 p{line-height:1.5em;}
-h1{font-size:1.75em;/* 28px */
-line-height:1.7em;font-family:helvetica,verdana;}
-h2{font-size:1.5em;/* 24px */
-line-height:1.7em;font-family:helvetica,verdana;}
-h3{font-size:1.25em;/* 20px */
-line-height:1.7em;font-family:helvetica,verdana;}
+h1{font-size:1.75em;line-height:1.7em;font-family:helvetica,verdana;}
+h2{font-size:1.5em;line-height:1.7em;font-family:helvetica,verdana;}
+h3{font-size:1.25em;line-height:1.7em;font-family:helvetica,verdana;}
 h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;}
 html,body{width:100%;height:100%;}
 body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;}
@@ -42,23 +31,25 @@ body h2,
 body h3,
 body h4,
 body h5,
-body h6{font-family:"Nobile","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#144fb2;font-style:normal;}
-#wrap {min-height: 100%;}
-#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;}
-#header{background-color:#e88f00;top:0;font-size:14px;}
-#footer{background-color:#000000;bottom:0;position: relative;margin-top:-40px;clear:both;}
-.header,.footer{width:700px;margin-right:auto;margin-left:auto;}
+body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;}
+#wrap{min-height:100%;}
+#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;}
+#header{background:#000000;top:0;font-size:14px;}
+#footer{bottom:0;background:#000000 url(footerbg.png) repeat-x 0 top;position:relative;margin-top:-40px;clear:both;}
+.header,.footer{width:750px;margin-right:auto;margin-left:auto;}
 .wrapper{width:100%}
 #top,#bottom{width:100%;}
-#top{color:#888;background-color:#eee;height:300px;border-bottom:2px solid #ddd;}
-#bottom{color:#222;background-color:#ffffff;overflow:hidden;padding-bottom:80px;}
-.top,.bottom{width:700px;margin-right:auto;margin-left:auto;}
-.top{padding-top:100px;}
+#top{color:#000000;height:230px;
+background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;}
+#bottom{color:#222;background-color:#ffffff;}
+.top,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;}
+.top{padding-top:40px;}
+#middle{width:100%;height:100px;background:url(middlebg.png) repeat-x;border-top:2px solid #ffffff;border-bottom:2px solid #b2b2b2;}
 .app-welcome{margin-top:25px;}
 .app-name{color:#000000;font-weight:bold;}
 .bottom{padding-top:50px;}
-#left{width:325px;float:left;padding-right:25px;}
-#right{width:325px;float:right;padding-left:25px;}
+#left{width:350px;float:left;padding-right:25px;}
+#right{width:350px;float:right;padding-left:25px;}
 .align-left{text-align:left;}
 .align-right{text-align:right;}
 .align-center{text-align:center;}
@@ -67,7 +58,7 @@ ul.links li{list-style-type:none;font-size:14px;}
 form{border-style:none;}
 fieldset{border-style:none;}
 input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;}
-input[type=text]{}
+input[type=text]{width:205px;}
 input[type=submit]{background-color:#ddd;font-weight:bold;}
 /*Opera Fix*/
-body:before {content:"";height:100%;float:left;width:0;margin-top:-32767px;}
+body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;}
diff --git a/docs/narr/MyProject/myproject/static/pyramid.png b/docs/narr/MyProject/myproject/static/pyramid.png
new file mode 100644
index 000000000..347e05549
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/pyramid.png
diff --git a/docs/narr/MyProject/myproject/static/transparent.gif b/docs/narr/MyProject/myproject/static/transparent.gif
new file mode 100644
index 000000000..0341802e5
--- /dev/null
+++ b/docs/narr/MyProject/myproject/static/transparent.gif
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index 6ad23d44f..02fc00eeb 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -7,21 +7,21 @@
 	<meta name="description" content="pyramid web application" />
 	<link rel="shortcut icon" href="${request.application_url}/static/favicon.ico" />
 	<link rel="stylesheet" href="${request.application_url}/static/pylons.css" type="text/css" media="screen" charset="utf-8" />
+	<link href="http://fonts.googleapis.com/css?family=Neuton&amp;subset=latin" rel="stylesheet"  type="text/css" media="screen" charset="utf-8" />
 	<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
-	<!--[if !IE 7]>
-	<style type="text/css">
-		#wrap {display:table;height:100%}
-	</style>
+	<!--[if lte IE 6]>
+	<link rel="stylesheet" href="${request.application_url}/static/ie6.css" type="text/css" media="screen" charset="utf-8" />
 	<![endif]-->
 </head>
 <body>
 	<div id="wrap">
-		<div id="header">
-			<div class="header">The Pyramid Web Application Development Framework</div>
-		</div>
 		<div id="top">
 			<div class="top align-center">
-				<img src="${request.application_url}/static/logo.png" width="300" height="80"/>
+				<div><img src="${request.application_url}/static/pyramid.png" width="750" height="169" alt="pyramid"/></div>
+			</div>
+		</div>
+		<div id="middle">
+			<div class="middle align-center">
 				<p class="app-welcome">
 					Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
 					the Pyramid web application development framework.
@@ -31,22 +31,19 @@
 		<div id="bottom">
 			<div class="bottom">
 				<div id="left" class="align-right">
-					<h3>Search Pyramid documentation</h3>
+					<h2>Search documentation</h2>
 					<form method="get" action="http://docs.pylonshq.com/pyramid/dev/search.html">
 		      			<input type="text" id="q" name="q" value="" />
-		      			<input type="submit" id="x" value="Search" />
+		      			<input type="submit" id="x" value="Go" />
 		  			</form>
 				</div>
 				<div id="right" class="align-left">
-					<h3>Pyramid links</h3>
+					<h2>Pyramid links</h2>
 					<ul class="links">
 						<li>
 							<a href="http://pylonshq.com">Pylons Website</a>
 						</li>
 						<li>
-							<a href="http://docs.pylonshq.com/">The Pylons Project Documentation</a>
-						</li>
-						<li>
 							<a href="http://docs.pylonshq.com/pyramid/dev/#narrative-documentation">Narrative Documentation</a>
 						</li>
 						<li>
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 725d32725..7c725690d 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -103,7 +103,7 @@ What Is The Pylons Project?
 ---------------------------
 
 :app:`Pyramid` is a member of the collection of software published under the
-Pylons Project.  :Pylons software is written by a loose-knit community of
+Pylons Project.  Pylons software is written by a loose-knit community of
 contributors.  The `Pylons Project website <http://docs.pylonshq.com>`_
 includes details about how :app:`Pyramid` relates to the Pylons Project.
 
diff --git a/docs/narr/project.png b/docs/narr/project.png
index 78db4dbbe..da5bc870b 100644
--- a/docs/narr/project.png
+++ b/docs/narr/project.png
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index aef134ff7..8901c1a4e 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -881,3 +881,67 @@ provided as convenience and example.
 
 See :ref:`unittesting_chapter` for more information about writing
 :app:`Pyramid` unit tests.
+
+Modifying Package Structure
+----------------------------
+
+It is best practice for your application's code layout to not stray too much
+from accepted Pyramid paster template defaults.  If you refrain from changing
+things very much, other Pyramid coders will be able to more quickly
+understand your application.  However, the code layout choices made for you
+by a paster template are in no way magical or required.  Despite the choices
+made for you by any paster template, you can decide to lay your code out any
+way you see fit.
+
+For example, the configuration method named
+:meth:`~pyramid.configuration.Configurator.add_view` requires you to pass a
+:term:`dotted Python name` or a direct object reference as the class or
+function to be used as a view.  By default, the ``pyramid_starter`` paster
+template would have you add view functions to the ``views.py`` module in your
+package.  However, you might be more comfortable creating a ``views``
+*directory*, and adding a single file for each view.
+
+If your project package name was ``myproject`` and you wanted to arrange all
+your views in a Python subpackage within the ``myproject`` :term:`package`
+named ``views`` instead of within a single ``views.py`` file, you might:
+
+- Create a ``views`` directory inside your ``mypackage`` 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*.
+
+Then change the __init__.py of your myproject project (*not* the
+``__init__.py`` you just created in the ``views`` directory, the one in its
+parent directory).  For example, from something like:
+
+.. code-block:: python
+
+    config.add_view('myproject.views.my_view',
+                    renderer='myproject:templates/mytemplate.pt')
+
+To this:
+
+.. code-block:: python
+
+    config.add_view('myproject.views.blogs.my_view',
+                    renderer='myproject:templates/mytemplate.pt')
+
+You can then continue to add files to the ``views`` directory, and refer to
+views or handler classes/functions within those files via the dotted name
+passed as the first argument to ``add_view``.  For example:
+
+.. code-block:: python
+
+    config.add_view('myproject.views.anothermodule.my_view',
+                    renderer='myproject:templates/anothertemplate.pt')
+
+This pattern can be used to rearrage code referred to by any Pyramid API
+argument which accepts a :term:`dotted Python name` or direct object
+reference.
+
+