I finally got around to write my very own HTML documentation system. Of course, this may be pointless and useless, but I found the alternatives "out there" lacking this or that (obviously!). So here I am, trying to automate the process of producing documentation like that of CLAZY, which I hand-crafted in the past. In the process, needless to say, I got carried away and got lost in the land of featurism only to contemplate my overall ignorance of most things webbish.
As usual, Edi Weitz came to my rescue by offering his CL-WHO and HTML-TEMPLATE, which raised a question: which of the two approaches is best? Note that the answer should consider how many dependencies my system files can have.
Let's start with the simple problem I have: I need to produce a .html file that contains, say, a "header" for my documentation. I could do it using CL-WHO in the following way (just a snippet, not working...)
(defun produce-header-file (fs header-pathname) (declare (type frameset fs) (type pathname header-pathname)) (let ((fs-order (frameset-order fs)) (fs-head-title (frameset-head-title fs)) (fs-body-title (frameset-body-title fs)) ) (with-open-file (hs header-pathname :direction :output :if-exists :supersede :if-does-not-exist :create) (with-html-output (hs hs :indent t) (fmt "~A" (cl-fad:pathname-as-file header-pathname)) (fmt +doctype-frameset-control-string+) (:html (:head (:title (str fs-head-title)) (:link :rel "stylesheet" :href "clstyle.css")) (:body :style "margin: 0pt 0pt 0pt 0pt;" (:div :class "header" :style "padding-left: 2em; padding-top: 5pt; color: #41286f; font-size: 14pt" (:strong (str fs-body-title)) (:div :class "navigation" :style "right: 2m" (:a :href "index.html" :class "navigation-link-selected" :target "_parent" (str "Home")) ))))) )))
Or I could use HTML-TEMPLATE and ship around a "template" file like the following (again, this is just a snippet and contains errors):
<!-- header.html --> <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <title><!-- TMPL_VAR HEAD_TITLE --></title> <link rel="stylesheet" href="clstyle.css"> </head> <body style="margin: 0pt 0pt 0pt 0pt;"> <div class="header" style="padding-left: 2em; padding-top: 5pt; "> <strong><i><!-- TMPL_VAR BODY_TITLE --></i></strong><br/> <div class="navigation" style="right: 2m"> <!-- TMPL_LOOP frames --> <!-- TMPL_IF current_frame --> <a href=<!-- TMPL_VAR frame --> class="navigation-link-selected" target=_parent><!-- TMPL_VAR f_nav_name ->></a> <!-- TMPL_ELSE --> <a href=<!-- TMPL_VAR frame --> class="navigation-link" target=_parent><!-- TMPL_VAR f_nav_name ->></a> <!-- /TMPL_IF --> <!-- /TMPL_LOOP --> </div> </div> </body> </html> <!-- end of file : header.html -->