[Japanese] [English]


Title: langhelp: Integrated help system in EmacsRuby

1 What's new

1.1 [2006/09/21] 0.9.8 released

1.2 [2006/08/03] 0.9.7 released

1.3 [2006/02/09] 0.9.6 released

1.4 [2006/02/01] 0.9.5 released

1.5 [2005/12/23] 0.9.4 released

1.6 [2005/12/11] 0.9.3 released

1.7 [2005/12/10] 0.9.2 released

1.8 [2005/12/03] 0.9.1 released

1.9 [2005/12/02] 0.9.0 released

Initial release

2 Abstract

Langhelp creates an index of documents of various programming languages and shell commands. Langhelp enables you to search documents instantly in Emacs. If you are a programmer, then you may sometimes wonder, what is the usage of this function? If you use Unices, then you may wonder, what is the usage of this command? Langhelp answers the question INSTANTLY.

Currently langhelp supports languages and commands below.

planner, xnee, html, svn, bison, 
cvs, libtool, latex, ratpoisonrc, java, 
id-utils, gengetopt, wget, lua, php, 
texinfo, c++, c, standards, grep, 
rb, gdb, diff, octave, scheme, 
python, global, flex, tcl, m4, 
sed, screenrc, xmms-shell, gzip, perl, 
emacs-lisp, ruby, autoconf, sgrep, hurd, 
el4r, binutils, awk, graphviz-dot, makefile, 

Langhelp may be the first tool written in EmacsRuby in the world. In other words, langhelp is an practical example of EmacsRuby script.

3 Screenshots

4 Environment

Langhelp depends on some tools.

I use Debian GNU/Linux and Emacs21*1. Langhelp probably works on other GNU/Linux or Unices. Langhelp also works on Windows(Meadow + Cygwin).

Langhelp does not compete against other document-lookup tools, but langhelp INTEGRATES document-lookup tools. The more you have tools, the more usefule langhelp is.

4.1 Langhelp support tools

The following tools are not mandatory but strengthens langhelp.

various Info documents

Langhelp treats Info documents VERY EASY.

w3m, emacs_w3m

W3m processes HTML documents. Emacs-w3m is a WWW browser in Emacs, uses w3m internally.


Ri looks up Ruby methods. It is bundled in Ruby distribution.

Ri for (X)Emacs

This tool speeds up `ri' calls.


Luahelp searches Lua documents.

Emacs Lisp List

There are MANY EmacsLisp programs.


Major mode for editing screenrc.


Major mode for editing ratpoisonrc. It is bundled in ratpoison distribution.


Visible bookmarks in buffer.

5 Install

First install el4r to run EmacsRuby scripts.

ruby -ropen-uri -e 'URI("http://www.rubyist.net/~rubikitch/archive/el4r-1.0.4.tar.gz").read.display' > el4r-1.0.4.tar.gz
tar xzf el4r-1.0.4.tar.gz
cd el4r-1.0.4
ruby setup.rb

ruby -S el4r-rctool -p
ruby -S el4r-rctool -i

Then install langhelp. Please execute the following commands.

ruby -ropen-uri -e 'URI("http://www.rubyist.net/~rubikitch/archive/langhelp-0.9.8.tar.gz").read.display' > langhelp-0.9.8.tar.gz
tar xzvf langhelp-0.9.8.tar.gz

When you failed, please download it from the next link.

Then, install it.

cd langhelp-0.9.8
ruby setup.rb

Victor Borja created Gentoo ebuild. Thanks.

Boris Daix created Debian package. Thanks. Put the following to your /etc/apt/sources.list:

deb http://alysse.dyndns.org/~bdaix/debian/packages unstable/
deb-src http://alysse.dyndns.org/~bdaix/debian/packages unstable/

6 Configuration file

The user configuration file of langhelp is `~/.langhelp/config', which is pure Ruby script.

If you install langhelp for the first time, copy `data/langhelp/config.sample' to `~/.langhelp/config'.

cp data/langhelp/config.sample ~/.langhelp/config

Writing config from scratch is very very hard, so `config.sample' is also installed. The following command indicates where `config.sample' is.

ruby -rrbconfig -e 'puts "#{Config::CONFIG["datadir"]}/langhelp/config.sample"'

6.1 Quick start

First execute `mklanghelp' command. Beware two hyphens.

mklanghelp --all

If you use Windows, you may use `ruby -S'.

ruby -S mklanghelp --all

Probably you would encounter with many error messages because the documents does not exist in the path specified in the config file. Errors are ignored and langhelp does the best effort.

Errors are erased by

Modify your config file after reading comments in config file CAREFULLY.

6.2 Language-specific configuration

Langhelp works in Emacs. Many major modes for programming languages exist. Normally the name of major mode ends with `-mode'.

Langhelp knows currently editing language by major mode. Here the `language name' of langhelp is defined: the string removed `-mode' from major mode name. For instance, ruby-mode is the major mode of Ruby, then the language name is `ruby'. graphviz-dot-mode is the major mode of Graphviz DOT language, then the language name is `graphviz-dot'.

If there is no major mode, use `define-generic-mode' or `define-derived-mode' to fabricate major mode. It is needed that the major mode ONLY exists.

(define-generic-mode 'foo-mode (list ?#) nil nil nil nil)
(define-derived-mode baz-mode fundamental-mode "baz")

Language-specific configuration means to specify @lang variable properly.

The details are written in `data/langhelp/config.sample'.

6.3 Checking document definitions

Since version 0.9.8, langhelp provides document definition check function. Point the line containing file name (document definition Hash) and issue

M-x langhelp-test-definition-this-line

You check the index the document definition outputs.

6.4 Troubleshooting

The following command does syntax check.

ruby -c ~/.langhelp/config

7 How to Use

7.1 Making Indexes

Langhelp has indexes by language. `mklanghelp' command makes indexes based on config file.

Invoking langhelp without arguments shows the usage.

Usage: mklanghelp [options] [languages]
Supported languages: planner, xnee, html, svn, bison, cvs, libtool, latex, ratpoisonrc, java, id-utils, gengetopt, wget, lua, php, texinfo, c++, c, standards, grep, rb, gdb, diff, octave, scheme, python, global, flex, tcl, m4, sed, screenrc, xmms-shell, gzip, perl, emacs-lisp, ruby, autoconf, sgrep, hurd, el4r, binutils, awk, graphviz-dot, makefile, sh
    -a, --all                        Output index of all languages.
        --home=DIR                   Output directory of index files.
        --suffix=SUFFIX              Suffix of index files [default: .e]
    -c, --init-script FILE           Initialize script name [default: /home/rubikitch/.langhelp/mklanghelp-init.rb]
    -f                               Suppress read of init script.
        --langs                      Output supported languages.
        --stdout                     Output index into stdout.
    -e, --eval=EXP                   Evaluate.
    -d, --debug                      Output stack trace when error occurred.

Invoking langhelp with arguments makes indexes of each languages. With `--all' option, languages makes indexes of all languages.

mklanghelp ruby emacs-lisp
mklanghelp --all

7.2 In Emacs

If you want to access documents managed by langhelp, type

C-c s

If you are upgrading from 0.9.0, add the line below to config.

@langhelp_key = '\C-cs'

Then, the `*langhelp:langname*' buffer appears and starts incremental search.

When you call langhelp, many lines containing EmacsLisp sexps appear. Sexp are colored by font-lock. Langhelp accesses information sources by evaluating sexps, so called lisp-hyperlink. This means that if you define the appropriate EmacsLisp function then langhelp can call EVERYTHING!

The cursor movement is performed by vi-like k/j as well as p/n.

To follow the link, type l or RET. Some links specify LINE to jump(line number or line contents). l or RET follow link in this line and put point on screen top. ;, L or C follow link in this line and center point in window. o follows link in this line and selects the help window to edit.

Following many links increase buffers. Typing K or D kills the help window buffer.

Typing C-o in incremental search does search refinement.

If bm.el are installed, typing m makes bookmark. P and N perform bookmark jump.

C-c C-n toggles narrowing to this section.

Typing C-c C-c exits langhelp and restore window configuration before langhelp was called.

Some people may perfer using `window manager' of Emacs. Install windows.el, escreen.el or elscreen.el when you want to save window configuration.

Remember to restart el4r when you remake indexes or modify config file after starting langhelp.

M-x el4r-boot

7.2.1 With `C-u'

Typing C-u C-c s shows langhelp full index, which is the list of languages managed by langhelp. Typing d in langhelp buffer also shows langhelp full index.

7.2.2 With `C-u C-u'

Typing C-u C-u C-c s searches current word. (since v0.9.7)

Alternatively typing

M-x langhelp-at-point

does the same thing.

8 Customizing

If you want to customize langhelp, read config file carefully.

As explaining in the config file there are some general purpose classes:`Grep', `W3MGrep'. `Grep' extracts lines matching the regexp and makes index. `W3MGrep' is almost the same as `Grep', the only difference is that the plain-text generated by w3m is to be processed. Manuals in plain-text or HTML can be imported into langhelp easily by regexp.

8.1 `~/.langhelp/mklanghelp-init.rb'

`~/.langhelp/mklanghelp-init.rb' is a Ruby script called by `mklanghelp' before processing.

Index classes are subclass of AbstractIndex. Write your own index classes in that file.

After defining new index classes you can use it by specifying config file.

@lang["foo"] = [
  {:FooIndex => true, :title=>"Foo", :cmd=>"fooindex"},

Then execute `mklanghelp'.

8.2 `~/.el4r/init.rb'

`~/.el4r/init.rb' are loaded when starting el4r.

Langhelp can treat any EmacsLisp functions as lisp-hyperlink. But the functions with the prefix `lh-' are colorized by font-lock.

8.3 If you do not like frames

Since v0.9.7, langhelp on Emacs on window systems uses its own frame. If you do not like frames, add

@NO_FRAME = true

to `~/.langhelp/config'.

9 Porting to Other Editors

`bin/mklanghelp' and `lib/langhelp/*.rb' does not utterly depend on specific editors. The task of These files is only to write indexes. Writing `Local Variables' section is only related to Emacs.

If you write the program corresponding to `lib/el4r/emacsruby/langhelp.rb', i.e. implementing all the functions appearing in the index, langhelp will work on other Lisp-based editors. Because sexps appearing in the index are not nested, reading the text between () will enable langhelp to work on non-Lisp-based editors.

If you port langhelp to other editors, I am willing to include your contribution.

10 Feedbacks

If you are trouble with langhelp, please post to the mail form at the end of this page freely. I am waiting for better configurations and new language supports.

11 License


Back to Top

Valid XHTML 1.0!
rubikitch(rubikitch __nos_pam__ At __nos_pam__ ruby-lang DoT org)

Mail Form
Name Mail

*1I currently use Emacs22.