Started adding functional descriptions to the documentation

git-svn-id: http://www.fractalconcept.com:8000/public/open-source/cl-typesetting@137 9d29c65d-f3d6-0310-ab0c-b43ff62e96ec

documentation/lisp-source/chapter-3.lisp

@@ -1,3 +1,66 @@
 (in-package :cl-pdf-doc)
 
-;;; Will contain cl-typesetting formatting explanations 
+;;; Will contain cl-typesetting formatting explanations 
+
+(defun chapter-3 ()
+
+  (chapter 
+      ("Ch 3: Document & Layout Functions")
+
+    (function-description 
+	("tt:with-document" :type "macro" :spec "(&rest args) &body body"
+			    :args '("&rest"
+				    (":author" "Author of the document.")
+				    (":title" "Documents Title")
+				    (":keywords" "Keywords of the document")
+				    (":subject" "Subject of the document")
+				    "&body"
+				    ("body" "Code generating the document")))
+      (body-text "The " (emphasize "with-document") " macro is the starting point for all documents. It is responsible for initializing all of the required objects need to generate the document. The arguments for author, title, keywords, subject are filled in a meta data for the document, and will appear under the document properties listings."))
+
+    (function-description
+	("tt:write-document" :type "defmethod" :spec "output-location &optional document" 
+			     :args '("Required"
+				     ("output-location" "string, pathname or stream, determines where the document content should be sent")
+				     "&Optional"
+				     ("document" "default *document, normal users will not need to provide this value")))
+      (body-text "Used to write out the given content of the document"))
+
+    (function-description 
+	("tt:draw-pages" :spec "content &rest args &key (size *default-page-size*) (orientation *default-page-orientation*) bounds margins header (header-top *default-page-header-footer-margin*) footer (footer-bottom *default-page-header-footer-margin*)  break finalize-fn &allow-other-keys)"
+			 :args '("Required"
+				 ("content" "A section of the doucment prepared by the macro compile-text")
+				 "&key"
+				 ("size" "Dimensions of the document's page")
+				 ("orientation" "Orientation of the document")
+				 ("bounds" "Media box; overwrites size and orientation when specified.")
+				 ("margins" "White space between the page's edge and the text, list of 4 numbers defining left-margin top-margin right-margin bottom-margin")
+				 ("header"  "Content or function of ftype (function (page) content which defines the header content of each page")
+				 ("header-top" "Distance between the top media edge and the header.")
+				 ("footer" "Content or function of ftype (function (page) content which defines the footer content of each page")
+				 ("footer-bottom" "Distance between the bottom media edge and the footer.")
+				 ("break" "Force new page ::= :before | :after | :always (both ends)")))
+      (body-text "Top level function useful for generating a multi-page section of the document. This function will start generating the content and will automatically overflow content onto another page as required to include all of the content in the document."))
+
+    (function-description 
+	("tt:paragraph" :type "macro" :spec "(&rest style) &body body" 
+			:args '("&rest"
+				("style" "These are all of the text style markers, used in the paragraph. The common markers are defined as follows")
+				(":top-margin" "space between the text of paragraph and the preceding document content")
+				(":bottom-margin" "space between the content of the paragraph and the following document content")
+				(":first-line-indent" "Number, the indentation of the first line of the paragraph, default is 0")
+				(":font" "designator of which font to utilize in this paragraph")
+				(":font-size" "size of the font to employ")
+				("text-x-scale" "")
+				(":color" "Foreground/text color")
+				(":background-color" "")
+				("h-align" "Content alignment ")
+				("left-margin" "")
+				("right-margin" "")
+				("pre-decoration" "")
+				("post-decoration" "")))
+      (body-text "Defines a paragraph with the given style set for the contents of the paragraph."))
+
+
+
+    ))

documentation/lisp-source/document.lisp

@@ -10,10 +10,11 @@
 (defun generate-cl-pdf-documentation (&key (file "/tmp/cl-pdf-doc.pdf"))
 
   (tt:with-document  
-      ()
+      (:author "Brian Sorg, Founder Liberating Insight LLC" :title "Cl-Pdf Documentation" :keywords "Cl-Pdf, Cl-Typesetting" :subject "Cl-Pdf User Document")
     (title-page)
     (chapter-1)
     (chapter-2)
+    (chapter-3)
     (appendix-a)
     (when pdf:*page* (typeset:finalize-page pdf:*page*))
     (tt:write-document file)))

documentation/lisp-source/infrastructure.lisp

@@ -104,4 +104,23 @@ Header-Size - Relates to the importance of the header. 1 Signals the most import
 	  (tt:put-string "Copyright Fort Wayne IN USA 2007"):eol
 	  (tt:verbatim print-stamp)
 	  (tt:verbatim 
-	   (format nil "   Page ~a" pdf:*page-number*)))))))
+	   (format nil "   Page ~a" pdf:*page-number*)))))))
+
+
+(defmacro function-description ((name &key (type "function") (spec "()") (return-value "nil") (args nil)) &body description)
+  "Macro to set up a macro or function description"
+  (let ((line (gensym)))
+    `(pdf:with-outline-level (,name (pdf:register-page-reference))
+      (header (tt:put-string (string-upcase ,name)) 4)
+      (header "Syntax" 5)
+      (body-text ,type " " (highlight ,name) " " (emphasize ,spec) " ==> " ,return-value)
+      (when ,args
+	(header "Arguments" 5)
+	(dolist (,line ,args)
+	  (if (listp ,line)
+	      (tt:paragraph (:font "Helvetica" :font-size 10 :left-margin 40)
+		(emphasize (tt:put-string (first ,line))) (tt:put-string (format nil ": ~a" (second ,line))))
+	      (tt:paragraph (:font "Helvetica" :font-size 10 :left-margin 20)
+		(highlight (tt:put-string ,line))))))
+      (header "Description" 5)
+      ,@description)))