Skip to content

Commit

Permalink
First draft of new Vim help doc
Browse files Browse the repository at this point in the history 
Completely overhaul the Vim help doc as 90% of the information within it
was outdated, links didn't work and it wasn't syntax highlighted.
  • Loading branch information
@axvr
axvr committed Oct 25, 2024
1 parent 268955c commit 0069d5c
Show file tree
Hide file tree
Showing 2 changed files with 172 additions and 178 deletions.
7 changes: 3 additions & 4 deletions README.mkd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,7 @@ Feel free to [request features and/or file bug reports](https://github.com/ionid

## Requirements

* Neovim or Vim 8.0+
- Python support is not required as of now. This may or may not change in the future.
* Neovim or Vim 8+

* [.NET Core SDK](https://dotnet.microsoft.com/download)
- Required to install and run FsAutoComplete.
Expand Down Expand Up @@ -386,8 +385,8 @@ let g:fsharp#use_sdk_scripts = 0 " for net462 FSI

Sets additional arguments of the FSI instance Ionide-vim spawns and changes the behavior of FSAC accordingly when editing fsx files.
FSAC passes parameters on to the compiler for static analysis of script files.
Not all parameters are shared between the compiler and interpreter, so FSAC splits these into
1. `FSIExtraInteractiveParameters`: specifically for use with the interpreter process
Not all parameters are shared between the compiler and interpreter, so FSAC splits these into
1. `FSIExtraInteractiveParameters`: specifically for use with the interpreter process
2. `FSIExtraSharedParameters`: those parameters which should be passed both to the interactive interpreter *and* the compiler

Ionide-vim will pass all options from both of these parameters to the interpreter launched by `fsharp#fsi_command`
Expand Down
343 changes: 169 additions & 174 deletions doc/vim-fsharp.txt
View file
Original file line number Diff line number Diff line change
@@ -1,206 +1,201 @@
*vim-fsharp.txt* F# support for Vim
*FSharp* *F#* *fsharp* *vim-fsharp*
===============================================================================
# #
# ███████╗███████╗██╗ ██╗ █████╗ ██████╗ ██████╗ #
# ██╔════╝██╔════╝██║ ██║██╔══██╗██╔══██╗██╔══██╗ #
# █████╗ ███████╗███████║███████║██████╔╝██████╔╝ #
# ██╔══╝ ╚════██║██╔══██║██╔══██║██╔══██╗██╔═══╝ #
# ██║ ███████║██║ ██║██║ ██║██║ ██║██║ #
# ╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ #
# #
===============================================================================
CONTENTS *fsharp-contents*

1. Dependencies.................................|fsharp-dependencies|
2. Usage........................................|fsharp-usage|
3. Options......................................|fsharp-options|
4. Commands.....................................|fsharp-commands|
5. Mappings.....................................|fsharp-mappings|
6. Credits......................................|fsharp-credits|

===============================================================================
DEPENDENCIES *fsharp-dependencies*

Required:~
- Vim 7.3 or higher with Python 2 or 3 support
- Mono OR .NET Framework
- F#

Optional:~
- Syntastic plugin (for syntax and type checking)
NOTE: Must be enabled (see |'g:syntastic_fsharp_checkers'|)

===============================================================================
USAGE *fsharp-usage*

Syntax highlighting and linting will trigger upon opening a `*.fs`, `*.fsi`,
or `*.fsx` file. Using omni completion will begin the fsautocomplete process.

Suggestion: Install a completer such as NeoComplete or SuperTab

===============================================================================
OPTIONS *fsharp-options*

*'g:syntastic_fsharp_checkers'*
Use this option to enable syntastic integration >
let g:syntastic_fsharp_checkers=['syntax']
<
*'g:fsharp_only_check_errors_on_write'*
Use this option to disable "on the fly" syntax checking >
let g:fsharp_only_check_errors_on_write = 1
<
*'g:fsharpbinding_debug'*
Use this option to enable debug-mode and inspect fsautocomplete behavior: >
let g:fsharpbinding_debug = 1
<
This will create two log files `log.txt` and `log2.txt` in your temporary folder
(i.e. `/tmp/`)
*vim-fsharp.txt* Ionide-Vim: F# support for Vim *F#* *ionide-vim*

*'g:fsharp_xbuild_path'*
Use this option set the msbuild/xbuild path >
let g:fsharp_xbuild_path = "/path/to/xbuild/or/msbuild"
<

*'g:fsharp_test_runner'*
Use this option to point to a suitable test runner (such as nunit-console.exe) >
let g:fsharp_test_runner = "/path/to/test/runner"
<
███████╗███████╗██╗ ██╗ █████╗ ██████╗ ██████╗
██╔════╝██╔════╝██║ ██║██╔══██╗██╔══██╗██╔══██╗
█████╗ ███████╗███████║███████║██████╔╝██████╔╝
██╔══╝ ╚════██║██╔══██║██╔══██║██╔══██╗██╔═══╝
██║ ███████║██║ ██║██║ ██║██║ ██║██║
╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝

*'g:fsharp_completion_helptext'*
Use this option to disable helptext during auto completion. Turn off if
completion is too slow >
let g:fsharp_completion_helptext = 0
<

*'g:fsharp_map_keys'*
Use this option to disable default bindings >
let g:fsharp_map_keys = 0
<
1. Usage ......................................... |fsharp-usage|
2. FSAutoComplete LSP ............................ |fsharp-projects|
3. F# Interactive ................................ |fsharp-interactive|
4. Linting ....................................... |fsharp-linting|
5. Formatting .................................... |fsharp-formatting|
6. Credits ....................................... |fsharp-credits|

*'g:fsharp_map_prefix'*
Use this option to override the default prefix of `<leader>` >
let g:fsharp_map_prefix = 'cp'
<
Set to `cp` in this example
==============================================================================
1. USAGE *fsharp-usage*

*'g:fsharp_map_fsisendline'*
Use this option to override the default mapping to send the current line to
fsharp interactive >
let g:fsharp_map_fsisendline = 'p'
<
Set to `p` in this example
Syntax highlighting, linting and the LSP will trigger upon opening a `*.fs`,
`*.fsi`, or `*.fsx` file.

*'g:fsharp_map_fsisendsel'*
Use this option to override the default mapping to send the current selection
to fsharp interactive >
let g:fsharp_map_fsisendsel = 'p'
<
Set to `p` in this example
Dependencies ~

*'g:fsharp_map_gotodecl'*
Use this option to override the default mapping to go to declaration in the
current window >
let g:fsharp_map_gotodecl = 'g'
<
Set to `g` in this example
* Neovim or Vim 8+

*'g:fsharp_map_gobackfromdecl'*
Use this option to override the default mapping to go back to where go to
declaration was triggered >
let g:fsharp_map_gobackfromdecl = 'b'
<
Set to `b` in this example
Note: If using Neovim < 0.5 or Vim, you will need to install:
https://github.com/autozimu/LanguageClient-neovim

* .NET SDK
https://dotnet.microsoft.com/download

* FsAutoComplete (`dotnet tool install -g fsautocomplete`)

==============================================================================
2. FSAUTOCOMPLETE LSP *fsharp-projects* *FSAC*

Ionide uses FSAutoComplete (FSAC) as its LSP server. See |fsac-settings| on
configuring FSAutoComplete.

------------------------------------------------------------------------------
2.1. FSAUTOCOMPLETE COMMANDS *fsac-commands*

*:FSharpShowLoadedProjects* - Shows the currently loaded projects.
*:FSharpParseProject* - Loads specified projects (`sln` or `fsproj`).
*:FSharpReloadWorkspace* - Reloads currently loaded projects.
*:FSharpUpdateServerConfig* - Updates FSAutoComplete (FSAC) configuration.

------------------------------------------------------------------------------
2.2. FSAUTOCOMPLETE SETTINGS *fsac-settings*

TODO: explain FSAC settings.

*'g:fsharp#backend'*
Set the LSP client used. Available values:
* `'nvim'` - Default on Neovim v0.5+.
* `'languageclient-neovim'` - Default if Vim or Neovim < v0.5.
* `'disable'` - Turn off LSP integration.

The `'languageclient-neovim'` option sets the LSP client to be
https://github.com/autozimu/LanguageClient-neovim which needs installing
separately.


*'g:fsharp#fsautocomplete_command'*
Set the path to FSAutoComplete (FSAC).

*'g:fsharp_map_fsiinput'*
Override the default mapping to evaluate an fsharp expression in the fsi >
let g:fsharp_map_fsiinput = 'i'
Default: `['fsautocomplete', '--background-service-enabled']`

Use project local FSAC:
>
let g:fsharp#fsautocomplete_command =
\ [ 'dotnet', 'fsautocomplete', '--background-service-enabled' ]
<
------------------------------------------------------------------------------
2.3. NEOVIM LSP CLIENT SETTINGS *fsharp-nvim-lsp-client-settings*

===============================================================================
COMMANDS *fsharp-commands*
A bunch of configuration options for Ionide when using the Neovim LSP client.
Note: These do nothing when |'g:fsharp#backend'| is `'languageclient-neovim'`.

General commands:~
*:make*
:make
Calls xbuild on the fsproj for the current file (if any).
*'g:fsharp#lsp_recommended_colorscheme'*

*:FSharpParseProject*
:FSharpParseProject
Reparses all the project files and dependencies (this is done automatically
when opening a .fs or .fsi file).
Neovim's LSP client comes with no default colorscheme, so Ionide-vim sets
a VSCode-like one for LSP diagnostics by default. You can disable this by the
setting the option to `0`.

*:FSharpBuildProject*
:FSharpBuildProject
Calls xbuild on the fsproj for the current file (if any). Can also take a
path to the proj file to build.
*'g:fsharp#lsp_auto_setup'*

*:FSharpRunProject*
:FSharpRunProject
Runs the project for the current file (if any).
Ionide-vim automatically sets up the server config for the Neovim LSP client.
If you would rather control it manually set this option to `0`.

*:FSharpRunTests*
:FSharpRunTests
If `g:fsharp_test_runner` is set it will build the current project and run
any tests. (Currently only tested with nunit-console.exe)

*:FSharpToggleHelptext*
:FSharpToggleHelptext
toggles g:fsharp_completion_helptext. (See below for details)
*'g:fsharp#lsp_codelens'*

FSharp interaction commands:~
By default Ionide-vim will automatically refresh Neovim's LSP client CodeLens
on |CursorHold| and |InsertLeave|. To disable this set this option to `0`.

`:FsiEval`
:FsiEval
Evaluates an fsharp expression in the fsi
==============================================================================
3. F# INTERACTIVE *fsharp-interactive* *FSI*

`:FsiEvalBuffer`
:FsiEvalBuffer
Evaluates the entire buffer in the fsi
Ionide-vim can integrate with F# Interactive (FSI). FSI is displayed using
the builtin |:terminal| feature introduced in Vim 8 and Neovim.

`:FsiReset`
:FsiReset
Resets the current fsharp interactive
------------------------------------------------------------------------------
3.1. FSI COMMANDS *fsi-commands*

`:FsiRead`
:FsiRead
Outputs any lines written by the fsi but not yet output as vim messages
*:FsiShow* - Opens FSI in a split window.
*:FsiEval* - Evaluates given expression in the FSI.
*:FsiEvalBuffer* - Evaluates the current buffer in the FSI.
*:FsiReset* - Resets the current FSI session.

`:FsiClear`
:FsiClear
Deletes all text from the fsi output buffer but doesn't reset the fsi
session.
------------------------------------------------------------------------------
3.2. FSI MAPPINGS *fsi-mappings*

`:FsiShow`
:FsiShow
Opens the _fsi-out_ buffer in a split window
<M-CR> (Alt + Enter)
* Normal mode: sends the current line to FSI.
* Visual mode: sends the selection to FSI.
* Opens the FSI window but the cursor does not focus it.
* When |'g:fsharp#fsi_keymap'| is set to `'vim-fsharp'` the mapping for this
becomes <leader>i
* When |'g:fsharp#fsi_keymap'| is set to `'custom'` the mapping for this can
be configured with *'g:fsharp#fsi_keymap_send'*

===============================================================================
MAPPINGS *fsharp-mappings*
<M-@> (Alt + @)
* Toggles the FSI window.
* When opened, the cursor focuses to the FSI window (unlike <M-CR>).
* When |'g:fsharp#fsi_keymap'| is set to `'vim-fsharp'` the mapping for this
becomes <leader>e
* When |'g:fsharp#fsi_keymap'| is set to `'custom'` the mapping for this can
be configured with *'g:fsharp#fsi_keymap_toggle'*

General:~
------------------------------------------------------------------------------
3.3. FSI SETTINGS *fsi-settings*

<leader>t
Echoes the type of the expression currently pointed to by the cursor
<leader>d
Go to declaration in current window
<leader>s
Takes you back from where go to declaration was triggered. Experimental
*'g:fsharp#fsi_command'*
Set the command to launch FSI. Default: `'dotnet fsi'`

FSharp Interactive:~
<A-CR> OR
<leader>i
Send either the current selection or the current line to the fsharp
interactive and echoes the output the first line of the output. All
output will be written to the fsi-out buffer.
*'g:fsharp#fsi_extra_interactive_parameters'*
*'g:fsharp#fsi_extra_shared_parameters'*

===============================================================================
CREDITS *fsharp-credits*
Sets additional arguments of the FSI instance Ionide-vim spawns and changes
the behavior of FSAC accordingly when editing F# files. FSAC passes parameters
on to the compiler for static analysis of script files. Not all parameters are
shared between the compiler and interpreter, so FSAC splits these into

Syntax and indent files by kongo2002 <github.com/kongo2002>:
http://github.com/kongo2002/fsharp-vim
* `FSIExtraInteractiveParameters`: specifically for the interpreter process.
* `FSIExtraSharedParameters`: for both to the interpreter and compiler.

Adapted from Tim Robinson <github.com/timrobinson>:
http://github.com/timrobinson/fsharp-vim
>
===============================================================================
Ionide-vim will pass all options from both of these parameters to the
interpreter launched by |'g:fsharp#fsi_command'|.

Default: `let g:fsharp#fsi_extra_interactive_parameters = ['--readline-']`


*'g:fsharp#fsi_window_command'*

Change how the FSI window opens. Default: `'botright 10new'`.


*'g:fsharp#fsi_focus_on_send'*

Control if sending line/selection to FSI should move the cursor focus to FSI.
Set this to `1` to turn this on.


*'g:fsharp#fsi_keymap'*

Change the default FSI mappings. Available values are:
* `'vscode'` - Default. Matches Ionide-VSCode.
* `'vim-fsharp'` - Use original vim-fsharp mappings.
* `'custom'` - Set the bindings yourself.

See |fsi-mappings| for more information on these values.

==============================================================================
4. LINTING *fsharp-linting*

Advanced linting is controlled by https://github.com/fsprojects/FSharpLint and
can be configured independent of Ionide by using its configuration mechanism.

==============================================================================
5. FORMATTING *fsharp-formatting*

Advanced formatting is controlled by https://github.com/fsprojects/fantomas
and can be configured independent of Ionide by using its configuration
mechanism.

==============================================================================
6. CREDITS *fsharp-credits*

Source code: https://github.com/ionide/Ionide-vim

Syntax and indent files by kongo2002: http://github.com/kongo2002/fsharp-vim

Adapted from Tim Robinson: http://github.com/timrobinson/fsharp-vim

==============================================================================

vim:tw=78:et:sw=4:sts=4:ts=8:ft=help:norl:

0 comments on commit 0069d5c

Please sign in to comment.