NAME
Emacs::Run::ExtractDocs - extract elisp docstrings to html form
SYNOPSIS
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");DESCRIPTION
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.
METHODS
- 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.
main methods
- 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
setters and getters
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.
automatic generation of accessors
- AUTOLOAD
MOTIVATION
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.
TODO
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).
SEE ALSO
AUTHOR
Joseph Brenner, <doom@kzsu.stanford.edu>, 02 Mar 2008
COPYRIGHT AND LICENSE
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.
BUGS
None reported... yet.