misc/fuel/README

   1 FUEL, Factor's Ultimate Emacs Library                              -*- org -*-
   2 -------------------------------------
   3
   4 FUEL provides a complete environment for your Factor coding pleasure
   5 inside Emacs, including source code edition and interaction with a
   6 Factor listener instance running within Emacs.
   7
   8 FUEL was started by Jose A Ortega as an extension to Eduardo Cavazos'
   9 original factor.el code. Eduardo is also responsible of naming the
  10 beast.
  11
  12 * Installation
  13
  14   FUEL comes bundled with Factor's distribution. The folder misc/fuel
  15   contains Elisp code, and there's a fuel vocabulary in extras/fuel.
  16
  17   To install FUEL, either add this line to your Emacs initialisation:
  18
  19   (load-file "<path/to/factor/installation>/misc/fuel/fu.el")
  20
  21   If all you want is a major mode for editing Factor code with pretty
  22   font colors and indentation, without running the factor listener
  23   inside Emacs, you can use instead:
  24
  25   (add-to-list 'load-path "<path/to/factor/installation>/fuel")
  26   (setq factor-mode-use-fuel nil)
  27   (require 'factor-mode)
  28
  29 * Basic usage
  30 *** Running the listener
  31
  32   If you're using the default factor binary and images locations inside
  33   the Factor's source tree, that should be enough to start using FUEL.
  34   Editing any file with the extension .factor will put you in
  35   factor-mode; try C-hm for a summary of available commands.
  36
  37   To start the listener, try M-x run-factor.
  38
  39   By default, FUEL will try to use the binary and image files in the
  40   factor installation directory. You can customize them with:
  41
  42     (setq fuel-listener-factor-binary <full path to factor>)
  43     (setq fuel-listener-factor-image <full path to factor image>)
  44
  45   Many aspects of the environment can be customized:
  46   M-x customize-group fuel will show you how many.
  47
  48 *** Faster listener startup
  49
  50   On startup, run-factor loads the fuel vocabulary, which can take a
  51   while. If you want to speedup the load process, type 'save' in the
  52   listener prompt just after invoking run-factor. This will save a
  53   factor image (overwriting the current one) with all the needed
  54   vocabs.
  55
  56 *** Connecting to a running Factor
  57
  58   'run-factor' starts a new factor listener process managed by Emacs.
  59   If you prefer to start Factor externally, you can also connect
  60   remotely from Emacs. Here's how to proceed:
  61
  62   - In the factor listener, run FUEL:
  63       "fuel" run
  64     This will start a server listener in port 9000.
  65   - Switch to Emacs and issue the command 'M-x connect-to-factor'.
  66
  67   That's it; you should be up and running. See the help for
  68   'connect-to-factor' for how to use a different port.
  69
  70 *** Vocabulary creation
  71
  72     FUEL offers a basic interface with Factor's scaffolding utilities.
  73     To create a new vocabulary directory and associated files:
  74
  75        M-x fuel-scaffold-vocab
  76
  77     and when in a vocab file, to create a docs file with boilerplate
  78     for each word:
  79
  80        M-x fuel-scaffold-help
  81
  82 * Quick key reference
  83
  84   (Triple chords ending in a single letter <x> accept also C-<x> (e.g.
  85   C-cC-eC-r is the same as C-cC-er)).
  86
  87 *** In factor source files:
  88
  89     - C-cz : switch to listener
  90     - C-co : cycle between code, tests and docs factor files
  91     - C-cs : switch to other factor buffer (M-x fuel-switch-to-buffer)
  92     - C-cr : switch to listener and refresh all loaded vocabs
  93     - C-x4s : switch to other factor buffer in other window
  94     - C-x5s : switch to other factor buffer in other frame
  95
  96     - M-. : edit word at point in Emacs (see fuel-edit-word-method custom var)
  97     - M-, : go back to where M-. was last invoked
  98     - M-TAB : complete word at point
  99     - C-cC-eu : update USING: line
 100     - C-cC-ev : edit vocabulary (M-x fuel-edit-vocabulary)
 101     - C-cC-ew : edit word (M-x fuel-edit-word-at-point)
 102     - C-cC-ed : edit word's doc (M-x fuel-edit-word-at-point)
 103
 104     - C-cC-er : eval region
 105     - C-M-r, C-cC-ee : eval region, extending it to definition boundaries
 106     - C-M-x, C-cC-ex : eval definition around point
 107     - C-ck, C-cC-ek : run file
 108
 109     - C-cC-da : toggle autodoc mode
 110     - C-cC-dd : help for word at point
 111     - C-cC-ds : short help word at point
 112     - C-cC-de : show stack effect of current sexp (with prefix, region)
 113     - C-cC-dp : find words containing given substring (M-x fuel-apropos)
 114     - C-cC-dv : show words in current file (with prefix, ask for vocab)
 115
 116     - C-cM-<, C-cC-d< : show callers of word or vocabulary at point
 117                         (M-x fuel-show-callers, M-x fuel-vocab-usage)
 118     - C-cM->, C-cC-d> : show callees of word or vocabulary at point
 119                         (M-x fuel-show-callees, M-x fuel-vocab-uses)
 120
 121     - C-cC-xs : extract innermost sexp (up to point)  as a separate word
 122     - C-cC-xr : extract region as a separate word
 123     - C-cC-xi : replace word at point by its definition
 124     - C-cC-xv : extract region as a separate vocabulary
 125     - C-cC-xw : rename all uses of a word
 126
 127 *** In the listener:
 128
 129     - TAB : complete word at point
 130     - M-. : edit word at point in Emacs
 131     - C-cr : refresh all loaded vocabs
 132     - C-ca : toggle autodoc mode
 133     - C-cp : find words containing given substring (M-x fuel-apropos)
 134     - C-cs : toggle stack mode
 135     - C-cv : edit vocabulary
 136     - C-ch : help for word at point
 137     - C-ck : run file
 138
 139 *** In the debugger (it pops up upon eval/compilation errors):
 140
 141     - g : go to error
 142     - <digit> : invoke nth restart
 143     - w/e/l : invoke :warnings, :errors, :linkage
 144     - q : bury buffer
 145
 146 *** In the help browser:
 147
 148     - h : help for word at point
 149     - v : help for a vocabulary
 150     - a : find words containing given substring (M-x fuel-apropos)
 151     - e : edit current article
 152     - ba : bookmark current page
 153     - bb : display bookmarks
 154     - bd : delete bookmark at point
 155     - n/p : next/previous page
 156     - l : previous page
 157     - SPC/S-SPC : scroll up/down
 158     - TAB/S-TAB : next/previous link
 159     - k : kill current page and go to previous or next
 160     - r : refresh page
 161     - c : clean browsing history
 162     - M-. : edit word at point in Emacs
 163     - C-cz : switch to listener
 164     - q : bury buffer
 165
 166 *** In crossref buffers
 167
 168     - TAB/BACKTAB : navigate links
 169     - RET/mouse click : follow link
 170     - h : show help for word at point
 171     - q : bury buffer