Documentation updates.

mdfiles/blocks.md

@@ -13,7 +13,8 @@ The Block class itself is quite simple: it provides a number of useful validatio
 functions, so that your code doesn't need to implement its own string and option
 validation in most cases, it allows your application to log user actions if
 needed, and it provides stub implementations of the page_display() and
-block_display() functions, one or both of which all subclasses need to override.
+block_display() functions, one or both of which all subclasses will need to
+override.
 
 Each subclass of Block gets a number of references to useful objects added to
 it on creation, and methods in the subclass can access them from $self. Some
@@ -54,8 +55,15 @@ by other blocks as needed, you'll need to write a block_display() method
 instead. Sometimes you may find that there could be two different 'views' of
 your block - say that your system includes a calendar, and sometimes it will
 be displayed as a small box in a page with other content, and sometimes
-the user will want to look at a page that shows nothing but the calendar.
-You can implement both page_dusplay() and block_display() for the block,
+the user will want to look at a page that shows the calendar full-size.
+You can implement both page_display() and block_display() for the block,
 the latter dealing with the situation where the calendar is embedded in a
 larger page, while the former handles the situation where the user is
 looking at just the calendar.
+
+You may also find that you can simplify your code as a whole by subclassing
+Block with a single class (MyAppBlock for example), placing code that is
+likely to be common across most or all of your various blocks in that
+subclass, and then further subclassing it to add block-specific code. This
+technique is used in both Megaphone and the Review webapp to avoid much
+unnecessary code replication.

mdfiles/overview.md

@@ -7,7 +7,7 @@ and may provide fewer features than some alternatives. However, they all present
 simple, concise interfaces that make them easy to use, in stark contrast to their
 more featureful brethren.
 
-At least I think they do. I might be biased, here.
+At least I think they do. I might be biased, however.
 
 Moreover, the intent behind this framework is to provide a simple base from which
 to rapidly develop web applications, with as few rigid rules as possible - if you
@@ -28,17 +28,22 @@ Block class, usually stored in the cunningly named `blocks` directory (see the
 Each subclass of Block should implement a piece of your webapp's functionality -
 how much or how little is left entirely up to you. The subclasses are loaded by
 the Modules class 'on demand', so the system does not attempt to load lots of
-redundant functionality when started.
+redundant functionality when started. You could implement your entire webapp in
+a single block if you wanted, but unless it is very simple a lot of unused code
+will be loaded each time a page is generated. Splitting your application up allows
+for more logical compartmentalisation of features, and reduces interpreter
+overhead.
 
 If you are using the Application class as the base of your webapp, it will
-automatically load one of the Block subclasses using the value specified in the
-'block' parameter in the query string or POSTed data (if the value in the `block`
-parameter is invalid or missing, a default 'initial block' specified in the
-configuration is loaded instead). For more about blocks, see the
-[Blocks](@ref blocks) documentation.
+perform all the framework setup process for you, and then load one of your
+Block subclasses to generate the actual page content. Application looks at the
+'block' parameter in the query string or POSTed data to determine which block
+to load, and if the value in the `block` parameter is invalid or missing, a
+default 'initial block' specified in the configuration is loaded instead. For
+more about blocks, see the [Blocks](@ref blocks) documentation.
 
-Once a block has been loaded by Application, it calls the block's page_display()
-function and prints the result to stdout, typically sending it back to the
+Once a block has been loaded, Application calls the block's page_display()
+method and prints the returned string to stdout, typically sending it back to the
 client web browser. What the block does in page_display is up to you: it could
 put together a HTML/XHTML page and return it, sending the page back to the user,
 or it could generate some other form of content and exit, bypassing the normal
@@ -52,3 +57,26 @@ Application hands execution over to your blocks is entirely up to you. See the
 [Blocks](@ref blocks) documentation for information about what gets passed to
 your block's constructor, and from there you can investigate the documentation
 for the modules provided in the framework.
+
+The Documentation
+-----------------
+
+The remainder of the documentation given here is split up into pages discussing
+specific aspects of the library:
+
+* [Blocks](@ref blocks) discusses the purpose, loading, and features of the
+  Block class and subclasses you may with to implement in your application.
+* [Structure](@ref structure) covers the suggested layout of files and directories.
+* [Configuration](@ref config) discusses the core configuration file, and the
+  optional settings table in the database.
+* [Sessions](@ref sessions) introduces the session handling feature of the
+  framework, and the various authentication schemes supported.
+* [Quick start](@ref quickstart) is a very brief run-through of the steps needed
+  to create a new webapp.
+
+Finally, remember this is Perl - the instructions contained here, and in
+the rest of the documentation, are not the only way to do it. If you find
+that following the structure discussed in this documentation is limiting, go ahead
+and try other ways - you'll undoubtedly be able to find many other ways of using
+the framework that better suit your needs.
+

mdfiles/structure.md

@@ -1,12 +1,18 @@
 Web App Structure                                            {#appstructure}
 =================
 
-The framework assumes that a specific files and directories are present in
+The framework assumes that a number of files and directories are present in
 order to work correctly. Note that you can easily change these if you handle
 the initialisation of the various modules in the framework yourself, but if
 you use the Application module to handle all the setup for you, you must
 follow the structure given in this documentation.
 
+Generally, .htaccess files are used to keep users out of many directories,
+but if you are concerned about any of the files being present in the web tree,
+you can move them out into non-web-accessible locations as long as you
+specify appropriate paths in the configuration and when creating an
+Application object.
+
 Structure overview
 ------------------