[Chicken-users] an utility for browsing the Chicken documentation

[Michele Simionato]

Hello Happy Chicken users!

I have a little script to browse the Chicken documentation which I find
quite useful. I wonder if we could have something similar in the
standard distribution. The usage is pretty obvious: for instance

$ chicken-help foreign-callback-wrapper

opens a browser window displaying the Chicken manual explanation of
foreign-callback-wrapper (which is here:
file:///usr/local/share/chicken/doc/chicken.html#index-foreign_002dcallback_002dwrapper-756).

It is enough to remember the beginning of the command and the script
will find the first occurrence of the abbreviation:

$ chicken-help foreign-callback

If the command cannot be found a not-found message is displayed; if
the script is invoked without arguments it opens the browser at the 
top level of the manual.

Here is the code:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

#!/usr/local/bin/csi -script
(require-extension regex miscmacros)

(define chicken-manual "/usr/local/share/chicken/doc/chicken.html")
(define default-browser (or (getenv "BROWSER") "mozilla"))
(define default-url (string-append "file://" chicken-manual))
(define pattern (regexp "href=\"(#index-[^\"]+)\""))

(define (search-line-by-line fname searcher)
  (define port (open-input-file fname))
  (define found #f)
  (do ((line (read-line port) (read-line port)))
      ((or found (eof-object? line)) (close-input-port port) found)
    (set! found (searcher line))))

(define (get-link cmd)
  (define command (string-append "<code>" cmd))
  (if*
   (search-line-by-line
    chicken-manual
    (lambda (line)
      (and (substring-index command line)
           (string-search pattern line))))
    (cadr it)
    (begin
       (printf "command ~a not found\n" cmd) (exit))))

(define (main)
  (let-optionals
   (command-line-arguments)
   ((cmd #f) (browser default-browser))
   (system
    (string-append
     browser " "  default-url (if cmd (get-link cmd) "")))))

(main)

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

As you see, the code is primitive, the location of the manual is
hard coded, Mozilla is hard-coded as default browser (unless you
set a BROWSER environment variable) and the script will stop working if
Felix changes the HTML structure of the manual (I noticed that
the links at the end of the manual are like this one

<li><a 
href="#index-foreign_002dcallback_002dwrapper-756"><code>foreign-callback-wrapper</code></a>:
<a href="#Callbacks">Callbacks</a></li>

so the script looks for lines containing "<code>foreign-callback-wrapper"
and find the 'href' y matching a regular expression). The script could
be enhanced to match regular expressions for the command and not
just poor man abbreviations, but it works enough for me even in 
the present state. Unfortunately, standard R5RS constructs are not
in the Chicken manual, so you cannot browse the documentation
for things like the 'do' macro :-(

An annoying issue is the fact that the script opens a new browser window at 
each call, whereas I would like to use the currently running browser
instance, at least with Mozilla (I don't know exactly why this happen,
I have a Python version of the same script which does the right thing
by invoking webbrowser.open).

After a little testing it seems to work enough. I want to
integrate it with Emacs, so I can get a description of the command I am 
looking at, since I really miss this feature. The quack mode
allows to browse the documentation but only for PLT scheme, not for
Chicken :-( This script is a first step in that direction.

Feel free to use if and to change it as you wish,


   Michele Simionato