From 0069d5c04749cf0c2583be9c867558dec9edffeb Mon Sep 17 00:00:00 2001 From: Alex Vear Date: Fri, 25 Oct 2024 01:54:07 +0100 Subject: [PATCH 1/2] First draft of new Vim help doc 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. --- README.mkd | 7 +- doc/vim-fsharp.txt | 343 ++++++++++++++++++++++----------------------- 2 files changed, 172 insertions(+), 178 deletions(-) diff --git a/README.mkd b/README.mkd index c161556..8d27df2 100644 --- a/README.mkd +++ b/README.mkd @@ -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. @@ -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` diff --git a/doc/vim-fsharp.txt b/doc/vim-fsharp.txt index b77ee76..e7739d0 100644 --- a/doc/vim-fsharp.txt +++ b/doc/vim-fsharp.txt @@ -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 `` > - 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 + (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 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* + (Alt + @) + * Toggles the FSI window. + * When opened, the cursor focuses to the FSI window (unlike ). + * When |'g:fsharp#fsi_keymap'| is set to `'vim-fsharp'` the mapping for this + becomes 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* - t - Echoes the type of the expression currently pointed to by the cursor - d - Go to declaration in current window - 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:~ - OR - 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 : - http://github.com/kongo2002/fsharp-vim + * `FSIExtraInteractiveParameters`: specifically for the interpreter process. + * `FSIExtraSharedParameters`: for both to the interpreter and compiler. -Adapted from Tim Robinson : - 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: From 5b0cec2750d9b6a7cbfe6964c9e9fa635ff37293 Mon Sep 17 00:00:00 2001 From: Alex Vear Date: Fri, 25 Oct 2024 21:35:08 +0100 Subject: [PATCH 2/2] Explain FSAutoComplete config options in Vim help doc --- README.mkd | 2 +- doc/vim-fsharp.txt | 55 ++++++++++++++++++++++++++++++++++------------ 2 files changed, 42 insertions(+), 15 deletions(-) diff --git a/README.mkd b/README.mkd index 8d27df2..7242ce6 100644 --- a/README.mkd +++ b/README.mkd @@ -359,7 +359,7 @@ let g:fsharp#automatic_reload_workspace = 1 " 0 to disable. *Default:* disabled ~~~.vim -let g:fsharp#show_signature_on_cursor_move = 0 " 1 to disable. +let g:fsharp#show_signature_on_cursor_move = 0 " 1 to enable. ~~~ > Note: this feature is known to be causing issues in some circumstances (#57, #58). diff --git a/doc/vim-fsharp.txt b/doc/vim-fsharp.txt index e7739d0..b4fc128 100644 --- a/doc/vim-fsharp.txt +++ b/doc/vim-fsharp.txt @@ -41,17 +41,10 @@ Ionide uses FSAutoComplete (FSAC) as its LSP server. See |fsac-settings| on configuring FSAutoComplete. ------------------------------------------------------------------------------ -2.1. FSAUTOCOMPLETE COMMANDS *fsac-commands* +2.1. SET UP LSP *fsac-set-up* -*:FSharpShowLoadedProjects* - Shows the currently loaded projects. -*:FSharpParseProject* - Loads specified projects (`sln` or `fsproj`). -*:FSharpReloadWorkspace* - Reloads currently loaded projects. -*:FSharpUpdateServerConfig* - Updates FSAutoComplete (FSAC) configuration. +Install FSAutoComplete globally with: `dotnet tool install -g fsautocomplete` ------------------------------------------------------------------------------- -2.2. FSAUTOCOMPLETE SETTINGS *fsac-settings* - -TODO: explain FSAC settings. *'g:fsharp#backend'* Set the LSP client used. Available values: @@ -75,7 +68,7 @@ Use project local FSAC: \ [ 'dotnet', 'fsautocomplete', '--background-service-enabled' ] < ------------------------------------------------------------------------------ -2.3. NEOVIM LSP CLIENT SETTINGS *fsharp-nvim-lsp-client-settings* +2.2. NEOVIM LSP CLIENT SETTINGS *fsharp-nvim-lsp-client-settings* A bunch of configuration options for Ionide when using the Neovim LSP client. Note: These do nothing when |'g:fsharp#backend'| is `'languageclient-neovim'`. @@ -97,6 +90,40 @@ If you would rather control it manually set this option to `0`. By default Ionide-vim will automatically refresh Neovim's LSP client CodeLens on |CursorHold| and |InsertLeave|. To disable this set this option to `0`. +------------------------------------------------------------------------------ +2.3. 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.4. FSAUTOCOMPLETE SETTINGS *fsac-settings* + +The FSAutoComplete (FSAC) LSP server is configured through Vim variables. +After setting the variables use |:FSharpUpdateServerConfig| to apply the +config changes. + +The Vim variables to configure FSAC all begin with `g:fsharp#` and followed by +snake_case versions of the FSAC setting name you wish to set. Not all FSAC +settings will do anything as Ionide-vim may be missing some features. + +If an FSAC setting is not specified, the "recommended default" in the FSAC +documentation will be used. Turn off all recomended defaults by setting +*'g:fsharp#use_recommended_server_config'* to `0`. + +List of all FSAC settings: https://github.com/ionide/FsAutoComplete#settings + +Some frequently used FSAC settings are: + * *'g:fsharp#automatic_workspace_init'* - Default: `1` (enabled) + * *'g:fsharp#automatic_reload_workspace'* - Default: `1` (enabled) + * *'g:fsharp#exclude_project_directories'* - Default: `[]` + * *'g:fsharp#linter'* - Default: `1` (enabled) + * *'g:fsharp#show_signature_on_cursor_move'* - Default: `0` (disabled) + * |'g:fsharp#fsi_extra_shared_parameters'| + * |'g:fsharp#fsi_extra_interactive_parameters'| + ============================================================================== 3. F# INTERACTIVE *fsharp-interactive* *FSI* @@ -106,10 +133,10 @@ the builtin |:terminal| feature introduced in Vim 8 and Neovim. ------------------------------------------------------------------------------ 3.1. FSI COMMANDS *fsi-commands* -*: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. + * *: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. ------------------------------------------------------------------------------ 3.2. FSI MAPPINGS *fsi-mappings*