Commits

Anonymous committed f5a1b21

Fixed a bug in tag library handling; the folder for tag libraries was still effectively hard-coded. Documentation in-progress, still very crude

Comments (0)

Files changed (6)

doctaglibraries/docs.lisp

+;; Copyright (c) 2010 Phil Hargett
+
+;; Permission is hereby granted, free of charge, to any person obtaining a copy
+;; of this software and associated documentation files (the "Software"), to deal
+;; in the Software without restriction, including without limitation the rights
+;; to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+;; copies of the Software, and to permit persons to whom the Software is
+;; furnished to do so, subject to the following conditions:
+
+;; The above copyright notice and this permission notice shall be included in
+;; all copies or substantial portions of the Software.
+
+;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+;; IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+;; FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+;; AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+;; LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+;; THE SOFTWARE.
+
+(in-tag-library :docs)
+
+(+tag-library :html)
+(+tag-library :script)
+
+(defhtmltag macro-docs
+    :content "Macro documentation will go here")
+
+(defhtmltag function-docs
+    :content "Function documentation will go here")
+
+(defhtmltag generic-function-docs
+    :content "Generic function documentation will go here")
+
+(defhtmltag variable-docs
+    :content "Variable documentation will go here")

doctemplates/doc_index.lisp

 (+tag-library :html)
 (+tag-library :script)
 
+(+tag-library :docs)
+
 (page 
  (+title "Documentation for hh-web-tags")
  (h1 "Overview")
- (p "Countless libraries exist to generate HTML.  What differentiates hh-web-tags from other generation libraries
-    is it's ability to generate not just HTML, but also CSS, Javascript, and other elements of a web-page all while
-    providing a modular framework for content."))
+ (p "Countless libraries exist to generate HTML, and so does " (em "hh-web-tags") ". But the latter generates not only HTML but CSS, 
+     Javascript, and even some page metadata. And it generates it all in a modular fashion.")
+ (p "A fundamental insight differentiates " (em "hh-web-tags") " from other such libraries: in Lisp terms, most libraries regard
+    HTML generation as a function with a single return value (the HTML).  Instead, hh-web-tags regards content generation
+    as a function returning multiple values" +mdash+ "a not unusual situation in Lisp, but uncommon (or unnatural) in
+    other languages.")
+ (p "For example, imagine another language (such as ColdFusion, or JSP) that defined a custom tag to create a sidebar navigation element
+     on a page:")
+ (code +lt+ "sidebar/" +gt+)
+ (p "In these other languages, that sidebar might result in a few divs added to a page:")
+ (code )
+ (h1 "Reference")
+ (h2 "Macros")
+ (macro-docs)
+ (h2 "Functions")
+ (function-docs)
+ (h2 "Generic Functions")
+ (generic-function-docs)
+ (h2 "Variables")
+ (variable-docs))

documentation.lisp

 (in-package :hh-web-tags)
 
 
-(deftemplates :tag-library-packages ( "hh-web-tags" )
+(deftemplates :tag-library-packages ( "hh-web-tags")
   :template-packages ( "hh-web-tags")
   :templates ((doc-index "doc_index.lisp"))
   :template-folder "doctemplates"
 						       :directory (pathname-directory documentation-path)))))
       (report "Generating documentation to directory ~s~%" documentation-path)
       (ensure-directories-exist documentation-path)
-      (with-open-file (os index-path :direction :output :if-does-not-exist :create :if-exists :overwrite)
+      (with-open-file (os index-path :direction :output :if-does-not-exist :create :if-exists :supersede)
 	(report "Generating index at ~s~%" index-path)
 	(write-string (doc-index) os))))
   t)

taglibraries.lisp

   "Minimum time in seconds for which a tag library must remain stale (e.g. not expire)
    before reloading from its source")
 
-(defvar *package-tag-library-folder* "taglibraries"
+(defvar *default-tag-library-folder* "taglibraries"
+  "The default folder for tag libraries")
+
+(defvar *package-tag-library-folder* *default-tag-library-folder*
   "Default folder within a package that contains the package's tag libraries")
 
 ;;;------------------------------------------------------------------------------------
 (defun create-folder-tag-library-provider (folder)
   (make-instance 'folder-tag-library-provider :folder folder))
 
-(defun create-asdf-system-tag-library-provider (system &key ((:folder *package)))
+(defun create-asdf-system-tag-library-provider (system &key ((:folder *package-tag-library-folder*) *package-tag-library-folder*))
   (make-instance 'folder-tag-library-provider 
 		 :folder (asdf:system-relative-pathname 
 					(asdf:find-system system) 

taglibraries/html.lisp

 (defentity +copy+ "©")
 (defentity +gt+ ">")
 (defentity +lt+ "<")
+(defentity +mdash+ "—")
 
 (defhtmltag p)
 (defhtmltag div)
   "Minimum time in seconds for which a template must remain stale (e.g. not expire,
    before reloading from its source")
 
-(defvar *package-template-folder* "templates"
+(defvar *default-template-folder* "templates"
+  "The default folder for templates")
+
+(defvar *package-template-folder* *default-template-folder*
   "The name of the folder within a package's folder structure where template 
    files are located")
 
+
 ;;;------------------------------------------------------------------------------------
 ;;; Conditions
 ;;;------------------------------------------------------------------------------------
      ;; create a macro to invoke the template
      (defun ,name (,@template-args)
        (let* ((*tag-library-provider-registry* (or *tag-library-provider-registry* ,(local-tag-library-provider-registry-symbol)))
-		 (*template-provider-registry* (or *template-provider-registry* ,(local-template-provider-registry-symbol)))
-		 (tmpl (or (find-cached-template ,path) 
-			  (load-template ,path (quote ,template-args)))))
+	      (*template-provider-registry* (or *template-provider-registry* ,(local-template-provider-registry-symbol)))
+	      (tmpl (or (find-cached-template ,path) 
+			(load-template ,path (quote ,template-args)))))
 	    (when tmpl
 	      (let ((*template* tmpl)
 		    (*package* (template-package tmpl)))
 					 `(create-asdf-system-template-provider (quote ,template-package) :folder ,template-folder)))
 				 template-packages)
 			 ;; always here by default
-			 (list `(create-asdf-system-template-provider 'hh-web-tags)))))
+			 (list `(create-asdf-system-template-provider 'hh-web-tags :folder *default-template-folder*)))))
 
        (defparameter ,tag-library-provider-registry
 	 (list ,@(append (mapcar (lambda (tag-library-package-spec)
 				     `(create-asdf-system-tag-library-provider (quote ,tag-library-package) :folder ,tag-library-folder)))
 				 tag-library-packages)
 			 ;; always here by default
-			 (list `(create-asdf-system-tag-library-provider 'hh-web-tags)))))
+			 (list `(create-asdf-system-tag-library-provider 'hh-web-tags :folder *default-tag-library-folder*)))))
 
        (let ((*tag-library-provider-registry* ,tag-library-provider-registry)
 	     (*template-provider-registry* ,template-provider-registry))