misc/vim/README.md

   1 Vim support for Factor
   2 ======================
   3
   4 This directory contains various support files that make editing
   5 Factor code more pleasant in Vim.
   6
   7 ## Installation
   8
   9 The file-layout exactly matches the Vim runtime structure, so
  10 you can install them by copying the contents of this directory
  11 into `~/.vim/` or the equivalent path on other platforms (open
  12 Vim and type `:help 'runtimepath'` for details).
  13
  14 ## File organization
  15
  16 The current set of files is as follows:
  17
  18 * ftdetect/factor.vim - Teach Vim when to load Factor support
  19   files.
  20 * ftplugin/factor.vim - Teach Vim to follow the Factor Coding
  21   Style guidelines. Contains an optional autopairs plugin for
  22   Factor. See configuration below.
  23 * ftplugin/factor-docs.vim - Teach Vim about documentation style
  24   differences.
  25 * plugin/factor.vim - Teach Vim some commands for navigating
  26   Factor source code. See configuration below.
  27 * syntax/factor.vim - Teach Vim about highlighting Factor source
  28   code syntax.
  29   * syntax/factor/generated.vim - Syntax highlighting lessons
  30     generated from a Factor VM.
  31 * indent/factor.vim - Teach Vim to automatically indent Factor
  32   source code.
  33
  34 ## Commands
  35
  36 The `plugin/factor.vim` file implements the following commands
  37 for navigating Factor source.
  38
  39 ### :FactorVocab factor.vocab.name
  40
  41 Opens the source file implementing the `factor.vocab.name`
  42 vocabulary.
  43
  44 ### :NewFactorVocab factor.vocab.name
  45
  46 Creates a new factor vocabulary under the working vocabulary
  47 root.
  48
  49 ### :FactorVocabImpl
  50
  51 Opens the main implementation file for the current vocabulary
  52 (name.factor). The keyboard shortcut `<Leader>fi` is bound to
  53 this command.
  54
  55 ### :FactorVocabDocs
  56
  57 Opens the documentation file for the current vocabulary
  58 (name-docs.factor). The keyboard shortcut `<Leader>fd` is bound
  59 to this command.
  60
  61 ### :FactorVocabTests
  62
  63 Opens the unit test file for the current vocabulary
  64 (name-tests.factor). The keyboard shortcut `<Leader>ft` is bound
  65 to this command.
  66
  67 ## Configuration
  68
  69 In order for the `:FactorVocab` command to work, you'll need to
  70 set some variables in your vimrc file.
  71
  72 ### g:FactorRoot
  73
  74 This variable should be set to the root of your Factor
  75 installation. The default value is `~/factor`.
  76
  77 ### g:FactorVocabRoots
  78
  79 This variable should be set to a list of Factor vocabulary
  80 roots. The paths may be either relative to g:FactorRoot or
  81 absolute paths. The default value is `["core", "basis", "extra",
  82 "work"]`.
  83
  84 ### g:FactorNewVocabRoot
  85
  86 This variable should be set to the vocabulary root in which
  87 vocabularies created with NewFactorVocab should be created. The
  88 default value is `work`.
  89
  90 ### g:EnableFactorAutopairs
  91
  92 This variable should be set to 1 if you want to enable the
  93 autopairs functionality.
  94
  95 ## Note
  96
  97 The `syntax/factor/generated.vim` syntax highlighting file is
  98 automatically generated to include the names of all the
  99 vocabularies Factor knows about.
 100 To regenerate it manually, run the following code in the
 101 listener:
 102
 103     "editors.vim.generate-syntax" run
 104
 105 or run it from the command line:
 106
 107     factor -run=editors.vim.generate-syntax