getting help for your guile libraries in emacs

[Andy Wingo]

Greets,

I just discovered an emacs trick that many of you probably know about,
but I figured it's work putting it out there.

Perhaps you have heard of C-h S, which is info-lookup-symbol. It opens
texinfo documentation for the symbol at point. However this isn't very
useful for me for two reasons.

The first reason is that the the info files that are installed in my
system are outdated -- I would want docs for CVS guile rather than 1.6,
for example. The second reason is that often I want docs for libraries
that aren't a base part of Guile, for example g-wrap or guile-gnome-gtk.

Fortunately both of these problems have solutions!

In your .emacs:

    (setq scheme-mode-doc-specs nil)

    (setq Info-additional-directory-list
          (list "~/src/guile-1.8/doc/ref"
                "~/src/guile-1.8/doc/goops"))
    (setq scheme-mode-doc-specs
          '(("(guile)Procedure Index" nil "^ -+ .*: " " ")
            ("(guile)Variable Index" nil "^ -+ .*: " " ")
            ("(guile)R5RS Index" nil "^ -+ .*: " " ")
            ("(goops)Function and Variable Index" nil "^ -+ .*: " " ")))

    (info-lookup-add-help
     :mode 'scheme-mode
     :regexp "[^()`',\" \t\n]+"
     :ignore-case nil
     :doc-spec scheme-mode-doc-specs)

This tells emacs that if it doesn't find an info file in the normal dirs
(set via INFOPATH or via the standard install preferences, such as
/usr/share/info), that it should look for info files in the
Info-additional-directory-list. Then, it says that when programming in
scheme-mode, to lookup help from the three indices in guile.info, and
the one from goops.info.

If you want to add other projects to this set, it is easy. For example,
put the following in your .emacs before the info-lookup-add-help line to
add info-lookup support for programming in guile-gnome:

    ;; Change this to nil if you use installed info files
    (setq guile-gnome-platform-dir "~/src/guile-gnome/platform/")

    (setq guile-gnome-platform-doc-paths
          '("glib/doc/gobject"
            "glib/doc/glib"
            "atk/doc"
            "pango/doc/pango"
            "pango/doc/pangocairo"
            "gtk/doc/gdk"
            "gtk/doc/gtk"
            "libglade/doc"
            "gnome-vfs/doc"
            "libgnome/doc"
            "libgnomeui/doc"
            "libgnomecanvas/doc"
            "gconf/doc"))

    (setq guile-gnome-platform-doc-names
          (mapcar
           (lambda (x)
             (string-match "^\\([a-z0-9-]+\\)/doc/?\\([a-z0-9-]+\\)?$" x)
             (or (match-string 2 x) (match-string 1 x)))
           guile-gnome-platform-doc-paths))

    (if guile-gnome-platform-dir
        (nconc Info-additional-directory-list
               (mapcar
                (lambda (path)
                  (concat guile-gnome-platform-dir path))
                guile-gnome-platform-docs)))
    (nconc scheme-mode-doc-specs
           (mapcan
            (lambda (wrapset)
              (list (list (concat "(guile-gnome-" wrapset ")Type Index") nil
                          "^ -+ .*: " " ")
                    (list (concat "(guile-gnome-" wrapset ")Function Index") nil
                          "^ -+ .*: " " ")))
            guile-gnome-platform-doc-names))

Pretty sweet. I hope this has helped someone, I know that it has helped
me. If you have other nifty hacks, please reply with some code snippets!

Peace,

Andy.

note: the index names of guile-gnome correspond to indices in as-yet
unreleased versions of guile-gnome; change them to the name of the
index nodes in the versions you have if you are interested in such
things
-- 
http://wingolog.org/