Emacs::Run::ExtractDocs - extract elisp docstrings to html form

   use Emacs::Run::ExtractDocs;
   my $reed = Emacs::Run::ExtractDocs->new({
              html_output_location => "/tmp/html",
   });

   # needed only if extract-docstrings.el isn't in load-path
   $reed->set_main_library("/tmp/new/elisp/extract-doctrings.el");

   $reed->elisp_docstrings_to_html("my-elisp-with-a-lot-of-docstrings.el");

Emacs::Run::ExtractDocs is a module that provides ways of working with the "docstrings" from emacs lisp packages and transforming them to other formats (at present, just html).

The central feature is the elisp_docstrings_to_html method, which can create a web page displaying the docstrings of any given elisp package.

Note that this is a very unusual "perl" package, in that it depends on having emacs installed (most likely, GNU/Emacs). Also, the extract-docstrings.el file that is shipped with this perl package must be installed somewhere in the emacs load-path.

new

Creates a new Emacs::Run::ExtractDocs object.

Takes a hashref as an argument, with named fields identical to the names of the object attributes. These attributes are:

html_output_location

Directory to put generated html.

main_library

Defaults to the elisp library name "extract-doctrings", so the system can find "extract-doctrings.el" once it's installed in the emacs load_path.

This can be set to a different library name, or more likely to a full path to the extract-docstrings.el in an unusual location. (This is very useful for testing, so that the code can run before it's installed.)

emacs_runner

An Emacs::Run object, used internally to call utility routines to probe the emacs installation, and run pieces of emacs lisp code. This will normally be created automatically, but if some unusual options are needed, one can be created externally and passed in as an attribute.

Takes an optional hashref as an argument, with named fields identical to the names of the object attributes.

init

Method that initializes object attributes and then locks them down to prevent accidental creation of new ones.

Any class that inherits from this one should have an init of it's own that calls this init. Otherwise, it's an internally used routine that is not of much interest to client coders.

elisp_docstrings_to_html

Given the name of an emacs lisp library (sans path or extension), or the file name of the library (with extension *.el), generates an html file in the standard location defined in the object: html_output_location

The output file naming convention is: <lib_name>_el.html

The naming convention in use here is that setters begin with "set_", but getters have *no* prefix: the most commonly used case deserves the simplest syntax (and mutators are deprecated).

These accessors exist for all of the object attributes (documented above) irrespective of whether they're expected to be externally useful.

AUTOLOAD

Publishing code to a web site is essentially a systems administration task that is a very good fit for perl, but when the code you're publishing is emacs lisp, then emacs lisp is convenient for some of the tasks: hence this franken-project, gluing an emacs lisp package (extract-docstrings.el) into a perl module framework.

Emacs lisp has a feature where a "docstring" can be defined for each function or variable. This was primarily intended for the use of the emacs on-line help system, as opposed to the texinfo format used by the Gnu project for it's more formal documentation.

A practice started by Ilya Zakharovich when he wrote cperl-mode was to abuse this system of docstrings, in order to lower the bar to writing documentation: essentially it's a way of faking "pod" in elisp.

If your documentation is embedded in the emacs help system in the form of these docstrings, then when creating web pages about the code, it's useful to be able to extract the docstrings and format them as an html page.

And that's the small need this lash-up of a module fills.

o With this version, I use the (rather cheesy, in my opinion) cop-out of instructing the user to manually install the elisp somewhere in the load-path. Question: can this be automated?

o Currently, this is file-oriented: one *.el in, one *.html out. Would like to work on a set of elisp files, and handle internal links inside the set appropriately.

o Look into skeleton or tempo to do html headers and footers. At present, these are hardcoded strings (to dodge the old dependency on the non-standard template.el).

Emacs::Run

Joseph Brenner, <doom@kzsu.stanford.edu>, 02 Mar 2008

Copyright (C) 2008 by Joseph Brenner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

None reported... yet.