[bknr-devel] handler.lisp doc svn diff

[Thomas]

Index: bknr/web/src/web/handlers.lisp
===================================================================
--- bknr/web/src/web/handlers.lisp    (Revision 4409)
+++ bknr/web/src/web/handlers.lisp    (Arbeitskopie)
@@ -717,7 +717,12 @@
     (ensure-directories-exist spool-dir)
     spool-dir))
 
-(defmethod website-show-page ((website website) fn title)  
+(defmethod website-show-page ((website website) fn title)
+  "Method for generating the code for a normal website page.
+This gets called by with-bknr-page, whereas FN is a function with zero 
parameters
+containing the body of a with-bknr-page call. TITLE is the title as 
specified by a
+with-bknr-page call.
+Redefine to add your own behavior."
   (html   
    (:html
     (:head
@@ -733,6 +738,12 @@
      (session-info)))))
 
 (defmethod website-show-error-page ((website website) error)
+  "Method for generating the code for an error page.
+This gets called by an error handler in case something goes wrong on 
the server side.
+ERROR is a string describing the error which happened.
+
+Redefine to add your own behavior."
   (if (and (website-template-handler website)
            (error-template-pathname (website-template-handler website)))
       (send-error-response (website-template-handler website) 
(princ-to-string error))
@@ -747,12 +758,22 @@
       (:princ-safe error)))))))
 
 (defun show-page-with-error-handlers (fn &key (response +http-ok+) title)
+  "Sets up the http-response RESPONSE, content-type \"text/html; 
charset=UTF8\" and the xhtml stream which is used to send
+html to the clients. Then calls website-show-page for the current 
website with the given FN and TITLE."
   (setf (return-code*) response)
   (with-http-response (:content-type "text/html; charset=UTF-8" 
:response response)
     (with-http-body ()
       (website-show-page *website* fn title))))
 
 (defmacro with-bknr-page ((&rest args) &body body)
+  "Macro which sets up everything so you can directly write your html code.
+ARGS is a property list and can be any of the KEYWORD arguments which 
can also be given to
+show-page-with-error-handlers. Noteworthy in particular are :title and 
:response.
+The BODY will be given to website-show-page as a lambda function.
+
+Example:
+ * (with-bknr-page (:title \"Random Page\")
+    (:p (:princ-safe \"Randomness\"))) "
   `(show-page-with-error-handlers (lambda () (html , at body)) , at args))
 
 #+(or)
@@ -765,5 +786,6 @@
            , at body))))))
 
 (defun unpublish ()
+  "Unpublish a website by removing the BKNR dispatcher from the global 
*dispatch-table*"
   (setf *dispatch-table* (remove 'bknr-dispatch *dispatch-table*)
     *handlers* nil))