diff doc/philosophy.rst @ 61:55828c01e38f draft

More documenting.
author David Barts <n5jrn@me.com>
date Sun, 09 Jun 2019 10:37:45 -0700
parents 682cd33e564c
children
line wrap: on
line diff
--- a/doc/philosophy.rst	Sat Jun 08 07:43:15 2019 -0700
+++ b/doc/philosophy.rst	Sun Jun 09 10:37:45 2019 -0700
@@ -24,8 +24,8 @@
 
 I wanted to get on with the business of actually *using* TinCan to do things,
 so I didn't clutter it up with extra features that would be difficult to
-implement. (That's why there's currently no way to choose alternate templating engines
-to Chameleon. I tried to do that, and it proved overly complex. Maybe some day.)
+implement. (That's why there's currently no way to choose templating engines
+other than Chameleon. I tried to allow that, and it proved overly complex. Maybe some day.)
 
 ===========================
 Don't Be Gratuitously Bossy
@@ -46,7 +46,7 @@
 ===========
 
 It's maligned by many, but I personally like it, and it
-does *not* necessarily mean repudiating the MVC paradigm.
+does *not* necessarily mean repudiating the MVC paradigm (see :ref:`mvc-different-forms`).
 
 =====================
 Don't Repeat Yourself
@@ -59,21 +59,15 @@
 the relationships should be obvious by virtue of the similar names. The framework should figure
 it out and just "do the right thing" by default.
 
+.. _mvc-different-forms:
+
 ============================
 MVC Comes in Different Forms
 ============================
 
-If you show a little discipline, the template page will describe how data
-is presented to the user, and how he or she can interact with it. A view
-by any other name is still a view. The code-behind will tie that view into
-the underlying business logic, and bridge the gap between the two. A controller
-by any other name is still a controller.
+If a programmer shows a little discipline, the template page will describe how data is presented to the user, and how he or she can interact with it. A view by any other name is still a view. The code-behind will tie that view into the underlying business logic, and bridge the gap between the two. A controller by any other name is still a controller.
 
-If you don't show discipline, you can clutter your templates up with bits
-of Python code that represent controller logic, and clutter your controller up with
-bits of presentation details. Of course you can. That's not the framework's
-fault; that's the programmer's fault. Bad code can be written in any language,
-for any platform.
+If a programmer don't show discipline, s/he can clutter templates up with bits of Python code that represent controller logic, and clutter the controller up with bits of presentation details. Of course s/he can. That's not the framework's fault; that's the programmer's fault. Bad code can be written in any language, for any platform.
 
 ==================================================
 The Alternative is PHP or CGI, not Django or Flask
@@ -82,7 +76,7 @@
 I'm not the only one out there who doesn't like all the repeating yourself
 that most MVC frameworks make you do. There's still *a lot* of developers
 out there writing CGI scripts or using PHP, because CGI and PHP don't make
-you do all the busywork that frameworks do. (Can they be blamed? It really
+you do all the busywork that most frameworks do. (Can they be blamed? It really
 feels silly when all you want is to get a quick, small site up.)
 
 That's a pity, because CGI is hideously inefficient and PHP is, well, just
@@ -92,7 +86,7 @@
 Hopefully, by making it easier for people to code efficient web sites using
 a well-designed language that's easy to learn, I'll encourage more people
 to create efficient sites in a well-designed language. If not, well, at least
-I'll encourage *myself* to do so.
+I'll enable *myself* to do so.
 
 ============================================
 Meaningful Error Messages (If You Want Them)
@@ -105,5 +99,4 @@
 always have a log file with a traceback in it helping to pinpoint the
 cause.
 
-That is, assuming you enable logging. By default, it is turned off, simply
-because WSGI provides no default place for errors to go.
\ No newline at end of file
+(Note that WSGI provides no default means for logging errors, so if you're running TinCan via WSGI, it will be totally silent unless you pass ``tincan.launch`` a suitable logger. The simple test server created by the ``launch`` command always logs to standard error.)
\ No newline at end of file