[Checkins] SVN: grok/trunk/doc/tutorial.txt More tutorial work, introducing chapter-level headings as in the

[Martijn Faassen]

Log message for revision 73525:
  More tutorial work, introducing chapter-level headings as in the
  outline.
  

Changed:
  U   grok/trunk/doc/tutorial.txt

-=-
Modified: grok/trunk/doc/tutorial.txt
===================================================================
--- grok/trunk/doc/tutorial.txt	2007-03-25 02:21:40 UTC (rev 73524)
+++ grok/trunk/doc/tutorial.txt	2007-03-25 02:54:08 UTC (rev 73525)
@@ -1,3 +1,4 @@
+=============
 Grok tutorial
 =============
 
@@ -18,20 +19,41 @@
   Zope 3 (and Grok) however; try reading ``context`` or ``view``
   instead.
 
-Welcome to the Grok tutorial! Grok is an extension to Zope 3 that
-makes it much quicker and easier to develop web applications with Zope
-3, *without* losing the power and flexibility of Zope 3 itself. Grok
-builds on existing Zope 3 technology like the component architecture
-but exposes it in a different way to the developer; a way which we
-believe makes developing with Zope 3 easier and more fun.
+Welcome to the Grok tutorial! Grok is a powerful and flexible web
+application framework for Python developers. In this tutorial we will
+show you the various things you can do with Grok, and how Grok can
+help you build your web application. We'll start out simple, and will
+slowly go to more complex usage patterns.  
 
-In this tutorial we will show you the various things you can do with
-Grok. We'll start out simple, and will slowly go to more complex usage
-patterns. All you're expected to know is the Python programming
-language and an understanding of web programming. It also helps to be
-familiar with Zope Page Templates, though most of the examples should
-be fairly obvious even if you do not.
+All you're expected to know is the Python programming language and an
+understanding of basic web programming (HTML, forms, URLs). It also
+helps if you are familiar with Zope Page Templates, though most of the
+examples should be fairly obvious if you are already familiar with
+another templating language.
 
+We recommend beginners to follow the tutorial from top to bottom. The
+tutorial is designed to explain important concepts in order and slowly
+builds up from there.
+
+If you are more experienced, or just curious, you may want to skip
+around instead and read the pieces which interest you most. If
+something is unclear, you can always backtrack to previous sections.
+
+Grok is based on Zope 3 and is compatible with Zope 3, but you do not
+need to know Zope 3 (or Zope 2) at all to follow this tutorial. Grok
+builds on existing Zope 3 technology but exposes it in a different way
+to the developer. We believe Grok makes developing with Zope 3
+technology easier and more fun for beginners and experienced
+developers alike.
+
+Getting started with Grok
+=========================
+
+This chapter will help you get up and running with Grok, using the
+``grokproject`` tool. We create a new project with ``grokproject``,
+tell you how to get that project running so you can access it with a
+web browser.
+
 Setting up grokproject
 ----------------------
 
@@ -254,15 +276,27 @@
 .. include:: groktut/an_empty_grok_project/src/sample/configure.zcml
    :literal:
 
+Showing pages
+=============
+
+Showing web pages is what puts the *web* in "web applications". You
+start doing this with HTML templates, but Grok doesn't stop at
+templates. Most web pages in a web application will contain complex
+presentation logic that is better handled by separate Python code in
+conjunction with templates. This becomes especially important in more
+complex interactions with the user, such as form handling. After
+reading this chapter, you should already be able to write simple web
+applications with Grok.
+
 Publishing a simple web page
 ----------------------------
 
 Let's publish a simple static web page. Grok is geared towards web
 applications and therefore not really meant for publishing a large
 number of static (pregenerated) web pages. For that you're better off
-to use a specialized system such as Apache. But, to start a developing
-a web application we need to be able to put some simple HTML on the
-web, first.
+to use a specialized system such as Apache. Nonetheless, in order to
+develop any web application we need to know how to put some simple
+HTML on the web.
 
 As you saw previously, our ``Sample`` application has a stock front
 page, generated by grokproject. Let's change that.
@@ -756,6 +790,17 @@
 
   http://localhost:8080/test
 
+Models
+======
+
+Now we know how to show web pages, we need to go into what we are
+actually showing: the models. The models contain the
+display-independent logic of your application. In this chapter we will
+discuss a number of issues surrounding models: how your views connect
+to models, and how you can make sure the data in your models is stored
+safely. As the complexity of our sample applications grows, we will
+also go into a few more issues surrounding form handling.
+
 A view for a model
 ------------------