Getting HEΛP, Finally!

As I wrote in my last blog entry, I went back hacking on HEΛP.

HEΛP is the Common Lisp code documentation tool I started writing many years ago.

Apart from a little necessary Javascript and CSS, HEΛP is a full Common Lisp program, geared towards producing static documentation sites for CL code. I finally got around to modernize it and it is now ready for testing.

Evolution from (X)HTML to HTML5

The original HEΛP release was producing only (X)HTML output, moreover based on FRAMESETs.

Alas, when the first HEΛP release was made, FRAMESETs were falling out of fashion, and they were eventually deprecated with the advent of HTML5. An "upgrade" to HTML5 became then a necessity.

After a very long process, I finally finished the HTML5 port, plus some bells and whistles. All in all, the implementation uses <div ... > sections plus CSS to lay out the display, as I understand it is the proper coding fashion nowadays. The port uses the W3.CSS styles, which facilitated a number of choices. The result is rather pleasing, as far as I am concerned.

Example: Producing the HEΛP documentation

The HEΛP documentation (a form of it) is produced with the following command (hlp is one of the package nicknames):

(hlp:document #P"./" ; Just a "top directory"...
              :documentation-title "HEΛP"
              :format :html5
              :exclude-directories
              (list "doc/"
                    "js/"
                    "css/"
                    ".git/"
                    "tests/"
                    "tmp/"
                    "tools/"
                    )

              :exclude-files ; I run this from LW.
              (list "impl-dependent/ccl.lisp"
                    "impl-dependent/sbcl.lisp"
                    "utilities/document-helambdap.lisp"
                    "utilities/lambda-list-parsing.lisp"
                    )
              :only-documented t
              :only-exported t
              )

After much printing, the resulting static web pages are deposited in docs/html5/, unless overridden. The system also relies on some defaults which are handled by CLAD library.

Viewing the result.
For the time being, you can find the main page of HEΛP here. Navigating the bar on the left will allow you to see different bits and pieces fo the documentation. You will notice that you have different views of the documentation: a system view and a package view. The system view gives you also a view of the files and folders (modules) it contains.

Documentation strings are mostly left alone.
Unike for Emacs Lisp, there is no real agreement in the CL community about how to format documentation strings (if there is, I do not agree with it by definition - obviously). HEΛP wants to be able to document code that does not adopt any documentation string convention, therefore it treats documentation strings pretty much as they are, only adding some text in the guise of the Hyperspec entries.

Screenshot

Here are a couple of screenshots. Apologies for the bad resolution.

The Main View

The DIctionary View

Missing Pieces

There is one thing that is missing from HEΛP: the generation of proper crossreferencing. To do it correctly it will be necessary to somehow make some educated guesses about the content of documentation strings or agreeing on some markup to tag linkable items. Apart from that, at the time of this writing the doc strings are handled as enties in an has table, and that could be improved, as more indexes may be needed.

Of course, a major rewrite may also help, but time is a tyrant.

Any suggestion is welcome.

Try it!

Again, HEΛP is ready for you to try. You can clone the repository from Sourceforge.

... and remember: no Python or Ruby or Shell dependencies: pure CL (plus some Javascript, which is a functional language after all, whose first implementation was done in CL).

Enjoy!

---

'(cheers)

HTML in Common Lisp: code or fill?

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 -->

I am inclined to go the CL-WHO way. I do not have to ship around an extra file and record its location etc etc; yet the HTML-TEMPLATE does have appeal. Any ideas out there?

---

(cheers)