Merge of andrew-docs branch.

TODO.txt

@@ -1,10 +1,24 @@
-- Audit the rest of the docs for "view configuration" and "route
-  configuration" references, etc.
-
-- Basic WSGI documentation (pipeline / app / server).
-
 - Decide on ``unhook_zca`` argument to ``tearDown``.
 
 - Get rid of ITraverser hook in favor of IViewLookup.
 
 - Named notfound views.
+
+- Review:
+
+  [ ] Traversal
+
+  [ ] URL dispatch
+
+  [ ] Combining Traversal and URL Dispatch
+
+  [ ] Views
+
+- Review tutorials.
+
+- Review index.
+
+- Review API docs.
+
+- Basic WSGI documentation (pipeline / app / server).
+

docs/authorintro.rst

@@ -0,0 +1,64 @@
+Author Introduction
+===================
+
+This is the "author introduction", wherein, I, the author put stuff
+that goes nowhere else.
+
+The Genesis of :mod:`repoze.bfg`
+--------------------------------
+
+I wrote :mod:`repoze.bfg` after many years of writing applications
+using :term:`Zope`.  Zope provided me with a lot of mileage: it wasn't
+until almost a decade of succesfully creating applications using Zope
+that I decided to write a different web framework.  Although
+:mod:`repoze.bfg` takes inspiration from a variety of web frameworks,
+it owes more of its design ethos to Zope than any other.
+
+The "Repoze" brand existed before :mod:`repoze.bfg`.  One of the first
+packages developed as part of the Repoze brand was a package named
+:mod:`repoze.zope2`.  This was a package that allowed Zope 2
+applications to run under a :term:`WSGI` server without modification.
+Zope 2 did not have reasonable WSGI support at the time.
+
+During the development of the :mod:`repoze.zope2` package, I found
+that replicating the Zope 2 "publisher" -- the machinery that maps
+URLs to code -- was time-consuming and fiddly.  Zope 2 had evolved
+over many years, and emulating all of its edge cases was extremely
+difficult.  I finished the :mod:`repoze.zope2` package, and it
+emulates the normal Zope 2 publisher pretty well.  But during its
+development, it became clear that Zope 2 had simply begun to exceed my
+tolerance for complexity, and I began to look around for simpler
+options.
+
+I considered the using Zope 3 application server machinery, but it
+turned out that it had become more indirect than the Zope 2 machinery
+it aimed to replace, which didn't fulfill the goal of simplification.
+I also considered using Django and Pylons, but neither of those
+frameworks offer much along the axes of traversal, contextual
+declarative security, or application extensibility; these were
+features I had become accustomed to as a Zope developer.
+
+I decided that in the long term, creating a simpler, legacy-free
+framework that retained features I had become accustomed to when
+developing Zope applications was a more reasonable idea than
+continuing to use any Zope publisher or living with the limitations
+and unfamiliarities of a different framework.  The result is what is
+now :mod:`repoze.bfg`.
+
+Thanks
+------
+
+This book is dedicated to my grandmother, Dorothy Phillips.
+
+Thanks to the following people for providing expertise, resources, and
+software.  Without the help of these folks, neither this book nor the
+software which it details would exist: Paul Everitt, Tres Seaver,
+Andrew Sawyers, Malthe Borch, Carlos de la Guardia, Georg Brandl,
+Simon Oram of Electrosoup, Ian Bicking of the Open Planning Project,
+Jim Fulton of Zope Corporation, Tom Moroz of the Open Society
+Institute, and Todd Koym of Environmental Health Sciences.
+
+Special thanks to Guido van Rossum and Tim Peters for Python.
+
+Special thanks also to Tricia for putting up with me.
+

docs/build_book

@@ -0,0 +1,4 @@
+#!/bin/sh
+BOOK=1 make clean latex
+cd .build/latex
+make all

docs/conf.py

@@ -211,24 +211,29 @@
 
 \pagestyle{fancy}
 
+% header and footer styles
 \renewcommand{\chaptermark}[1]%
-{\markboth{\MakeUppercase{\thechapter.\ #1}}{}}
+  {\markboth{\MakeUppercase{\thechapter.\ #1}}{}
+  }
 \renewcommand{\sectionmark}[1]%
-{\markright{\MakeUppercase{\thesection.\ #1}}}
-\renewcommand{\headrulewidth}{0.5pt}
+  {\markright{\MakeUppercase{\thesection.\ #1}}
+  }
+
+% defaults for fancy style
+\renewcommand{\headrulewidth}{0pt}
 \renewcommand{\footrulewidth}{0pt}
 \fancyhf{}
 \fancyfoot[C]{\thepage}
-\fancyhead[RO]{\rightmark}
-\fancyhead[LE]{\leftmark}
 
+% plain style
 \fancypagestyle{plain}{
-  \fancyhf{} % empty header and footer
   \renewcommand{\headrulewidth}{0pt} % ho header line
-  \renewcommand{\footrulewidth}{0pt}% not footer line
-  \fancyfoot[C]{\thepage}% like fancy style
+  \renewcommand{\footrulewidth}{0pt}% no footer line
+  \fancyhf{} % empty header and footer
+  \fancyfoot[C]{\thepage}
 }
 
+% title page styles
 \makeatletter
 \def\@subtitle{\relax}
 \newcommand{\subtitle}[1]{\gdef\@subtitle{#1}}
@@ -242,7 +247,7 @@
 }
 \makeatother
 
-% Redefine these colors to your liking in the preamble.
+% Redefine link and title colors
 \definecolor{TitleColor}{rgb}{0,0,0}
 \definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
 \definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
@@ -252,29 +257,13 @@
 \definecolor{VerbatimBorderColor}{rgb}{1,1,1}
 
 \makeatletter
-% Notices / Admonitions
-%
-\newcommand{\py@veryheavybox}{
-  \setlength{\fboxrule}{2pt}
-  \setlength{\fboxsep}{7pt}
-  \setlength{\py@noticelength}{\linewidth}
-  \addtolength{\py@noticelength}{-2\fboxsep}
-  \addtolength{\py@noticelength}{-2\fboxrule}
-  \setlength{\shadowsize}{3pt}
-  \Sbox
-  \minipage{\py@noticelength}
-}
-\newcommand{\py@endveryheavybox}{
-  \endminipage
-  \endSbox
-  \fbox{\TheSbox}
-}
 \renewcommand{\py@noticestart@warning}{\py@heavybox}
 \renewcommand{\py@noticeend@warning}{\py@endheavybox}
 \renewcommand{\py@noticestart@note}{\py@heavybox}
 \renewcommand{\py@noticeend@note}{\py@endheavybox}
 \makeatother
 
+% icons in note and warning boxes
 \usepackage{ifthen}
 % Keep a copy of the original notice environment
 \let\origbeginnotice\notice
@@ -291,7 +280,20 @@
   \origendnotice% equivalent to original \end{notice}
 }
 
+% try to prevent code-block boxes from splitting across pages
 \sloppy
+\widowpenalty=300
+\clubpenalty=300
+\setlength{\parskip}{3ex plus 2ex minus 2ex}
+
+% suppress page numbers on pages showing part title
+\makeatletter
+\let\sv@endpart\@endpart
+\def\@endpart{\thispagestyle{empty}\sv@endpart}
+\makeatother
+
+% prevent page numbers in TOC (reset to fancy by frontmatter directive)
+\pagestyle{empty}
 """
 
 latex_elements = {
@@ -305,17 +307,58 @@
 
 from docutils import nodes
 
+# secnumdepth counter reset to 2 causes numbering in related matter;
+# reset to -1 causes chapters to not be numbered, reset to -2 causes
+# parts to not be numbered.
+
+#part	      -1
+#chapter       0
+#section       1
+#subsection    2
+#subsubsection 3
+#paragraph     4
+#subparagraph  5
+
 def frontmatter(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine):
-    return [nodes.raw('', '\\frontmatter\n', format='latex')]
+    return [nodes.raw(
+        '',
+        r"""
+\frontmatter
+% prevent part/chapter/section numbering
+\setcounter{secnumdepth}{-2}
+% suppress headers
+\pagestyle{plain}
+% reset page counter
+\setcounter{page}{1}
+% suppress first toc pagenum
+\addtocontents{toc}{\protect\thispagestyle{empty}} 
+""",
+        format='latex')]
 
 def mainmatter(name, arguments, options, content, lineno,
                content_offset, block_text, state, state_machine):
-    return [nodes.raw('', '\\mainmatter\n', format='latex')]
+    return [nodes.raw(
+        '',
+        r"""
+\mainmatter
+% allow part/chapter/section numbering
+\setcounter{secnumdepth}{2}
+% get headers back
+\pagestyle{fancy} 
+\fancyhf{}
+\renewcommand{\headrulewidth}{0.5pt}
+\renewcommand{\footrulewidth}{0pt}
+\fancyfoot[C]{\thepage}
+\fancyhead[RO]{\rightmark}
+\fancyhead[LE]{\leftmark}
+""",
+        format='latex')]
 
 def backmatter(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
-    return [nodes.raw('', '\\backmatter\n', format='latex')]
+    return [nodes.raw('', '\\backmatter\n\\setcounter{secnumdepth}{-1}\n',
+                      format='latex')]
 
 def setup(app):
     app.add_directive('frontmatter', frontmatter, 1, (0, 0, 0))

docs/copyright.rst

@@ -1,5 +1,5 @@
-Copyright and Trademarks
-========================
+Copyright, Trademarks, and Attributions
+=======================================
 
 *The repoze.bfg Web Application Framework*
 
@@ -11,7 +11,7 @@ Copyright |copy| 2008-2010, Agendaless Consulting.
 
 ISBN-13: 978-0-615-34537-6
 
-First publishing: 2010
+First print publishing: 2010
 
 All rights reserved.  This material may be copied or distributed only
 subject to the terms and conditions set forth in the `Creative Commons
@@ -30,14 +30,24 @@ similar license to this one.
    `less restrictive (BSD-like) license
    <http://repoze.org/license.html>`_ .
 
-**Trademarks**
-
 All terms mentioned in this book that are known to be trademarks or
 service marks have been appropriately capitalized.  However, use of a
 term in this book should not be regarded as affecting the validity of
 any trademark or service mark.
 
-**Attributions**
+Every effort has been made to make this book as complete and as
+accurate as possible, but no warranty or fitness is implied.  The
+information provided is on as "as-is" basis.  The author and the
+publisher shall have neither liability nor responsibility to any
+person or entity with respect to any loss or damages arising from the
+information contained in this book.  No patent liability is assumed
+with respect to the use of the information contained herein.
+
+Attributions
+------------
+
+Technical Reviewer:
+  Andrew Sawyers
 
 Cover Designer:
    `Electrosoup <http://www.electrosoup.co.uk>`_.
@@ -46,25 +56,20 @@ Used with permission:
    The :ref:`webob_chapter` chapter is adapted, with permission, from
    documentation originally written by Ian Bicking.
 
-**Warning and Disclaimer**
-
-Every effort has been made to make this book as complete and as
-accurate as possible, but no warranty or fitness is implied.  The
-information provided is on as "as-is" basis.  The author and the
-publisher shall have neither liability nor responsibility to any
-person or entity with respect to any loss or damages arising from the
-information contained in this book.  No patent liability is assumed
-with respect to the use of the information contained herein.
+Foreword:
+  Paul Everitt
 
-**Contacting The Publisher**
+Contacting The Publisher
+------------------------
 
 Please send documentation licensing inquiries, translation inquiries,
 and other business communications to `Agendaless Consulting
 <mailto:webmaster@agendaless.com>`_.  Please send software and other
 technical queries to the `repoze-dev maillist
 <http://lists.repoze.org/listinfo/repoze-dev>`_.
 
-**Source Code**
+Source Code
+-----------
 
 The source code for this book is available within the
 :mod:`repoze.bfg` software distribution, always available via

docs/glossary.rst

@@ -621,3 +621,18 @@ Glossary
    Agendaless Consulting
      A consulting organization formed by Paul Everitt, Tres Seaver,
      and Chris McDonough.  See also http://agendaless.com .
+
+   Jython
+     A `Python implementation <http://www.jython.org/>` written for
+     the Java Virtual Machine.
+
+   Python
+     The `programming language <http://python.org>` in which
+     :mod:`repoze.bfg` is written.
+
+   CPython
+     The C implementation of the Python language.  This is the
+     reference implementation that most people refer to as simply
+     "Python"; :term:`Jython`, Google's App Engine, and `PyPy
+     <http://codespeak.net/pypy/dist/pypy/doc/>`_ are examples of
+     non-C based Python implementations.

docs/index.rst

@@ -45,7 +45,7 @@ Narrative documentation in chapter form explaining how to use
    narr/introduction
    narr/install
    narr/configuration
-   narr/scanning
+   narr/firstapp
    narr/project
    narr/startup
    narr/urlmapping

docs/latexindex.rst

@@ -13,9 +13,9 @@ Front Matter
    :maxdepth: 1
 
    copyright.rst
-   thanks.rst
    conventions.rst
    foreword.rst
+   authorintro.rst
 
 .. mainmatter::
 
@@ -28,15 +28,14 @@ Narrative Documentation
    narr/introduction
    narr/install
    narr/configuration
-   narr/scanning
+   narr/firstapp
    narr/project
    narr/urlmapping
    narr/views
    narr/webob
    narr/templates
    narr/models
    narr/security
-   narr/hybrid
    narr/vhosting
    narr/events
    narr/environment