Many ways to follow link.
class HTML
class HTML
Initial release
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, sh,
Langhelp may be the first tool written in EmacsRuby in the world. In other words, langhelp is an practical example of EmacsRuby script.
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.
The following tools are not mandatory but strengthens langhelp.
Langhelp treats Info documents VERY EASY.
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.
This tool speeds up `ri' calls.
Luahelp searches Lua documents.
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.
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/
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"'
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.
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.
Example: (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'.
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.
The following command does syntax check.
ruby -c ~/.langhelp/config
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.
Example: mklanghelp ruby emacs-lisp mklanghelp --all
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
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.
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.
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.
`~/.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.
Example:
@lang["foo"] = [
{:FooIndex => true, :title=>"Foo", :cmd=>"fooindex"},
]
Then execute `mklanghelp'.
`~/.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.
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'.
`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.
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.
GPL
*1I currently use Emacs22.