Permalink
Browse files

Start working on a glossary. Also, start changing repoze.bfg occurren…

…ces to :mod: as I find them.
  • Loading branch information...
pauleveritt committed Jul 24, 2008
1 parent d4e2e0b commit c4d7f0b657c8863f34f3c9ea0bccb96aa7763877
Showing with 82 additions and 94 deletions.
  1. +57 −0 docs/glossary.rst
  2. +5 −1 docs/index.rst
  3. +20 −93 docs/narr/introduction.rst
View
@@ -0,0 +1,57 @@
+.. _glossary:
+
+============================
+ :mod:`repoze.bfg` Glossary
+============================
+
+.. glossary::
+
+ request
+ A ``WebOb`` request object.
+ response
+ An object that has three attributes: app_iter (representing an
+ iterable body), headerlist (representing the http headers sent
+ upstream), and status (representing the http status string). This
+ is the interface defined for ``WebOb`` response objects.
+ view
+ A "view" is a callable which returns a response object. It should
+ accept two values: context and request.
+ view name
+ The "URL name" of a view, e.g "index.html". If a view is
+ configured without a name, its name is considered to be the empty
+ string (which implies the "default view").
+ model
+ An object representing data in the system. A model is part of the
+ object graph traversed by the system. Models are traversed to
+ determine a context.
+ context
+ A model in the system that is found during traversal; it becomes
+ the subject of a view.
+ application registry
+ A registry which maps model types to views, as well as performing
+ other application-specific component registrations.
+ template
+ A file that is capable of representing some text when rendered.
+ interface
+ An attribute of a model object that determines its type.
+ security policy
+ An object that provides a mechanism to check authorization using
+ authentication data and a permission associated with a model. It
+ essentially returns "true" if the combination of the authorization
+ information in the model (e.g. an ACL) and the authentication data
+ in the request (e.g. the REMOTE_USER) allow the action implied by
+ the permission associated with the view (e.g. "add").
+ principal
+ A user id or group id.
+ permission
+ A permission is a string token that is associated with a view name
+ and a model type by the developer. Models are decorated with
+ security declarations (e.g. ACLs), which reference these tokens
+ also. A security policy attempts to match the view permission
+ against the model's statements about which permissions are granted
+ to which principal to answer the question "is this user allowed to
+ do this".
+ WSGI
+ `Web Server Gateway Interface <http://wsgi.org/>`_. This is a
+ Python standard for connecting web applications to web servers,
+ similar to the concept of Java Servlets.
View
@@ -4,6 +4,10 @@
repoze.bfg Documentation
==========================
+``repoze.bfg`` is a web application framework based on graph
+traversal. It is inspired by Zope's publisher, though less ambitious
+in scope. Instead, it embraces WSGI and existing WSGI software.
+
Narrative documentation
-----------------------
@@ -21,6 +25,7 @@ Narrative documentation in chapter form explaining how to use
narr/templates
narr/models
narr/security
+ glossary
Tutorials
----------
@@ -52,4 +57,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
View
@@ -1,37 +1,37 @@
-``repoze.bfg`` Introduction
-===========================
+:mod:`repoze.bfg` Introduction
+==============================
-``repoze.bfg`` is a web application framework based on graph
+:mod:`repoze.bfg` is a web application framework based on graph
traversal. It is inspired by Zope's publisher, and uses Zope
libraries to do much of its work. However, it is less ambitious and
less featureful than any released version of Zope's publisher.
-``repoze.bfg`` uses the WSGI protocol to handle requests and
-responses, and integrates Zope, Paste, and WebOb libraries to form the
-basis for a simple web object publishing framework.
+:mod:`repoze.bfg` uses the :term:`WSGI` protocol to handle requests
+and responses, and integrates Zope, Paste, and WebOb libraries to form
+the basis for a simple web object publishing framework.
Similarities with Other Frameworks
----------------------------------
-``repoze.bfg`` was inspired by Zope, Django, and Pylons.
+:mod:`repoze.bfg` was inspired by Zope, Django, and Pylons.
-``repoze.bfg``'s traversal is inspired by Zope. ``repoze.bfg`` uses
-the Zope Component Architecture ("CA") internally like Zope 2, Zope3,
-and Grok. Developers don't interact with the CA very much during
-typical development, however; it's mostly used by the framework
+:mod:`repoze.bfg`'s traversal is inspired by Zope. :mod:`repoze.bfg`
+uses the Zope Component Architecture ("CA") internally, as do Zope 2,
+Zope 3, and Grok. Developers don't interact with the CA very much
+during typical development, however; it's mostly used by the framework
developer rather than the application developer.
-Like Pylons, ``repoze.bfg`` is mostly policy-free. It makes no
+Like Pylons, :mod:`repoze.bfg` is mostly policy-free. It makes no
assertions about which database you should use, and its built-in
-templating facilities are only for convenience. It is essentially
-only supplies a mechanism to map URLs to view code and convention for
-calling those views. You are free to use third-party components in
-your application that fit your needs. Also like Pylons,
-``repoze.bfg`` is heavily dependent on WSGI.
+templating facilities are only for convenience. In essence, it only
+supplies a mechanism to map URLs to view code, along with a convention
+for calling those views. You are free to use third-party components
+in your application that fit your needs. Also like Pylons,
+:mod:`repoze.bfg` is heavily dependent on WSGI.
The Django docs state that Django is an "MTV" framework in their `FAQ
<http://www.djangoproject.com/documentation/faq/>`_. This also
-happens to be true for ``repoze.bfg``::
+happens to be true for :mod:`repoze.bfg`::
Django appears to be a MVC framework, but you call the Controller
the "view", and the View the "template". How come you don't use the
@@ -61,78 +61,5 @@ happens to be true for ``repoze.bfg``::
framework - that is, "model", "template", and "view." That breakdown
makes much more sense.
-Jargon
-------
-
-The following jargon is used casually in descriptions of
-``repoze.bfg`` operations.
-
-request
-
- A ``WebOb`` request object.
-
-response
-
- An object that has three attributes: app_iter (representing an
- iterable body), headerlist (representing the http headers sent
- upstream), and status (representing the http status string). This
- is the interface defined for ``WebOb`` response objects.
-
-view
-
- A "view" is a callable which returns a response object. It should
- accept two values: context and request.
-
-view name
-
- The "URL name" of a view, e.g "index.html". If a view is configured
- without a name, its name is considered to be the empty string (which
- implies the "default view").
-
-model
-
- An object representing data in the system. A model is part of the
- object graph traversed by the system. Models are traversed to
- determine a context.
-
-context
-
- A model in the system that is found during traversal; it becomes the
- subject of a view.
-
-application registry
-
- A registry which maps model types to views, as well as performing
- other application-specific component registrations.
-
-template
-
- A file that is capable of representing some text when rendered.
-
-interface
-
- An attribute of a model object that determines its type.
-
-security policy
-
- An object that provides a mechanism to check authorization using
- authentication data and a permission associated with a model. It
- essentially returns "true" if the combination of the authorization
- information in the model (e.g. an ACL) and the authentication data
- in the request (e.g. the REMOTE_USER) allow the action implied by
- the permission associated with the view (e.g. "add").
-
-principal
-
- A user id or group id.
-
-permission
-
- A permission is a string token that is associated with a view name
- and a model type by the developer. Models are decorated with
- security declarations (e.g. ACLs), which reference these tokens
- also. A security policy attempts to match the view permission
- against the model's statements about which permissions are granted
- to which principal to answer the question "is this user allowed to
- do this".
-
+To learn more about the concepts used by :mod:`repoze.bfg`, visit the
+:ref:`glossary` for a listing of definitions.

0 comments on commit c4d7f0b

Please sign in to comment.