FUEL, Factor's Ultimate Emacs Library                              -*- org -*-
-------------------------------------

FUEL provides a complete environment for your Factor coding pleasure
inside Emacs, including source code edition and interaction with a
Factor listener instance running within Emacs.

FUEL was started by Jose A Ortega as an extension to Eduardo Cavazos'
original factor.el code. Eduardo is also responsible of naming the
beast.

* Installation

  FUEL comes bundled with Factor's distribution. The folder misc/fuel
  contains Elisp code, and there's a fuel vocabulary in extras/fuel.

  To install FUEL, either add this line to your Emacs initialisation:

  (load-file "<path/to/factor/installation>/misc/fuel/fu.el")

  or

  (add-to-list load-path "<path/to/factor/installation>/fuel")
  (require 'fuel)

  If all you want is a major mode for editing Factor code with pretty
  font colors and indentation, without running the factor listener
  inside Emacs, you can use instead:

  (add-to-list load-path "<path/to/factor/installation>/fuel")
  (setq factor-mode-use-fuel nil)
  (require 'factor-mode)

* Basic usage

  If you're using the default factor binary and images locations inside
  the Factor's source tree, that should be enough to start using FUEL.
  Editing any file with the extension .factor will put you in
  factor-mode; try C-hm for a summary of available commands.

  To start the listener, try M-x run-factor.

  Many aspects of the environment can be customized:
  M-x customize-group fuel will show you how many.

* Quick key reference

  (Triple chords ending in a single letter <x> accept also C-<x> (e.g.
  C-cC-eC-r is the same as C-cC-er)).

*** In factor source files:

    - C-cz : switch to listener
    - C-co : cycle between code, tests and docs factor files

    - M-. : edit word at point in Emacs
    - M-TAB : complete word at point
    - C-cC-eu : update USING: line
    - C-cC-ev : edit vocabulary (M-x fuel-edit-vocabulary)
    - C-cC-ew : edit word (M-x fuel-edit-word-at-point)
    - C-cC-ed : edit word's doc (M-x fuel-edit-word-at-point)

    - C-cr, C-cC-er : eval region
    - C-M-r, C-cC-ee : eval region, extending it to definition boundaries
    - C-M-x, C-cC-ex : eval definition around point
    - C-ck, C-cC-ek : run file

    - C-cC-da : toggle autodoc mode
    - C-cC-dd : help for word at point
    - C-cC-ds : short help word at point
    - C-cC-de : show stack effect of current sexp (with prefix, region)
    - C-cC-dp : find words containing given substring (M-x fuel-apropos)
    - C-cC-dv : show words in current file (with prefix, ask for vocab)

    - C-cM-<, C-cC-d< : show callers of word at point
    - C-cM->, C-cC-d> : show callees of word at point

    - C-cC-xs : extract innermost sexp (up to point)  as a separate word
    - C-cC-xr : extract region as a separate word

*** In the listener:

    - TAB : complete word at point
    - M-. : edit word at point in Emacs
    - C-ca : toggle autodoc mode
    - C-cp : find words containing given substring (M-x fuel-apropos)
    - C-cs : toggle stack mode
    - C-cv : edit vocabulary
    - C-ch : help for word at point
    - C-ck : run file

*** In the debugger (it pops up upon eval/compilation errors):

    - g : go to error
    - <digit> : invoke nth restart
    - w/e/l : invoke :warnings, :errors, :linkage
    - q : bury buffer

*** In the help browser:

    - h : help for word at point
    - v : help for a vocabulary
    - a : find words containing given substring (M-x fuel-apropos)
    - e : edit current article
    - ba : bookmark current page
    - bb : display bookmarks
    - bd : delete bookmark at point
    - n/p : next/previous page
    - l : previous page
    - SPC/S-SPC : scroll up/down
    - TAB/S-TAB : next/previous link
    - k : kill current page and go to previous or next
    - r : refresh page
    - c : clean browsing history
    - M-. : edit word at point in Emacs
    - C-cz : switch to listener
    - q : bury buffer

*** In crossref buffers

    - TAB/BACKTAB : navigate links
    - RET/mouse click : follow link
    - h : show help for word at point
    - q : bury buffer