misc/fuel/README

   1 FUEL, Factor's Ultimate Emacs Library
   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     Alternatively, you can add the following line to your
  57     .factor-boot-rc file:
  58
  59        "fuel" require
  60
  61     This will ensure that the image generated while bootstrapping
  62     Factor contains fuel and the vocabularies it depends on.
  63
  64 *** Connecting to a running Factor
  65
  66     'run-factor' starts a new factor listener process managed by Emacs.
  67     If you prefer to start Factor externally, you can also connect
  68     remotely from Emacs. Here's how to proceed:
  69
  70     - In the factor listener, run FUEL: "fuel" run
  71       This will start a server listener in port 9000.
  72     - Switch to Emacs and issue the command 'M-x connect-to-factor'.
  73
  74   That's it; you should be up and running. See the help for
  75   'connect-to-factor' for how to use a different port.
  76
  77 *** Vocabulary creation
  78
  79     FUEL offers a basic interface to Factor's scaffolding utilities.
  80     To create a new vocabulary directory and associated files:
  81
  82        M-x fuel-scaffold-vocab
  83
  84     and when in a vocab file, to create a docs file with boilerplate
  85     for each word:
  86
  87        M-x fuel-scaffold-help
  88
  89 * Quick key reference
  90
  91   Triple chords ending in a single letter <x> accept also C-<x> (e.g.
  92   C-c C-e C-r is the same as C-c C-e r).
  93
  94 *** In factor source files:
  95
  96     Commands in parenthesis can be invoked interactively with
  97     M-x <command>, not necessarily in a factor buffer.
  98
  99     |--------------------+------------------------------------------------------------|
 100     | C-c C-z            | switch to listener (run-factor)                            |
 101     | C-c C-o            | cycle between code, tests and docs files                   |
 102     | C-c C-t            | run the unit tests for a vocabulary                        |
 103     | C-c C-r            | switch to listener and refresh all loaded vocabs           |
 104     | C-c C-s            | switch to other factor buffer (fuel-switch-to-buffer)      |
 105     | C-x 4 s            | switch to other factor buffer in other window              |
 106     | C-x 5 s            | switch to other factor buffer in other frame               |
 107     |--------------------+------------------------------------------------------------|
 108     | M-.                | edit word at point in Emacs (fuel-edit-word)               |
 109     | M-,                | go back to where M-. was last invoked                      |
 110     | M-TAB              | complete word at point                                     |
 111     | C-c C-e u          | update USING: line (fuel-update-usings)                    |
 112     | C-c C-e v          | edit vocabulary (fuel-edit-vocabulary)                     |
 113     | C-c C-e w          | edit word (fuel-edit-word-at-point)                        |
 114     | C-c C-e d          | edit word's doc (C-u M-x fuel-edit-word-doc-at-point)      |
 115     | C-c C-e l          | load vocabs in USING: form                                 |
 116     |--------------------+------------------------------------------------------------|
 117     | C-c C-e r          | eval region                                                |
 118     | C-M-r, C-c C-e e   | eval region, extending it to definition boundaries         |
 119     | C-M-x, C-c C-e x   | eval definition around point                               |
 120     | C-c C-k, C-c C-e k | run file (fuel-run-file)                                   |
 121     |--------------------+------------------------------------------------------------|
 122     | C-c C-d a          | toggle autodoc mode (fuel-autodoc-mode)                    |
 123     | C-c C-d d          | help for word at point (fuel-help)                         |
 124     | C-c C-d s          | short help word at point (fuel-help-short)                 |
 125     | C-c C-d e          | show stack effect of current sexp (with prefix, region)    |
 126     | C-c C-d p          | find words containing given substring (fuel-apropos)       |
 127     | C-c C-d v          | show words in current file (with prefix, ask for vocab)    |
 128     |--------------------+------------------------------------------------------------|
 129     | C-c M-<            | show callers of word or vocabulary at point                |
 130     |                    | (fuel-show-callers, fuel-vocab-usage)                      |
 131     | C-c M->            | show callees of word or vocabulary at point                |
 132     |                    | (fuel-show-callees, fuel-vocab-uses)                       |
 133     |--------------------+------------------------------------------------------------|
 134     | C-c C-x s          | extract innermost sexp (up to point) as a separate word    |
 135     |                    | (fuel-refactor-extract-sexp)                               |
 136     | C-c C-x r          | extract region as a separate word                          |
 137     |                    | (fuel-refactor-extract-region)                             |
 138     | C-c C-x v          | extract region as a separate vocabulary                    |
 139     |                    | (fuel-refactor-extract-vocab)                              |
 140     | C-c C-x i          | replace word by its definition (fuel-refactor-inline-word) |
 141     | C-c C-x w          | rename all uses of a word (fuel-refactor-rename-word)      |
 142     | C-c C-x a          | extract region as a separate ARTICLE: form                 |
 143     | C-c C-x g          | convert current word definition into GENERIC + method      |
 144     |                    | (fuel-refactor-make-generic)                               |
 145     |--------------------+------------------------------------------------------------|
 146
 147 *** In the listener:
 148
 149     |---------+----------------------------------------------------------|
 150     | TAB     | complete word at point                                   |
 151     | M-.     | edit word at point in Emacs                              |
 152     | C-c C-r | refresh all loaded vocabs                                |
 153     | C-c C-a | toggle autodoc mode                                      |
 154     | C-c C-p | find words containing given substring (M-x fuel-apropos) |
 155     | C-c C-s | toggle stack mode                                        |
 156     | C-c C-v | edit vocabulary                                          |
 157     | C-c C-w | help for word at point                                   |
 158     | C-c C-k | run file                                                 |
 159     |---------+----------------------------------------------------------|
 160
 161 *** In the debugger (it pops up upon eval/compilation errors):
 162
 163     |---------+-------------------------------------|
 164     | g       | go to error                         |
 165     | <digit> | invoke nth restart                  |
 166     | w/e/l   | invoke :warnings, :errors, :linkage |
 167     | q       | bury buffer                         |
 168     |---------+-------------------------------------|
 169
 170 *** In the help browser:
 171
 172     |-----------+----------------------------------------------------------|
 173     | h         | help for word at point                                   |
 174     | v         | help for a vocabulary                                    |
 175     | a         | find words containing given substring (M-x fuel-apropos) |
 176     | e         | edit current article                                     |
 177     | b a       | bookmark current page                                    |
 178     | b b       | display bookmarks                                        |
 179     | b d       | delete bookmark at point                                 |
 180     | n/p       | next/previous page                                       |
 181     | l         | previous page                                            |
 182     | SPC/S-SPC | scroll up/down                                           |
 183     | TAB/S-TAB | next/previous link                                       |
 184     | k         | kill current page and go to previous or next             |
 185     | r         | refresh page                                             |
 186     | c         | clean browsing history                                   |
 187     | M-.       | edit word at point in Emacs                              |
 188     | C-c C-z   | switch to listener                                       |
 189     | q         | bury buffer                                              |
 190     |-----------+----------------------------------------------------------|
 191
 192 *** In crossref buffers
 193
 194     |-----------------+-----------------------------|
 195     | TAB/BACKTAB     | navigate links              |
 196     | RET/mouse click | follow link                 |
 197     | h               | show help for word at point |
 198     | q               | bury buffer                 |
 199     |-----------------+-----------------------------|