[vim/vim] Improve documentation of <SID> (Issue #12073)
Jordan Mandel
Instructions: Replace the template text and remove irrelevant text (including this line)
Is your feature request about something that is currently impossible or hard to do? Please describe the problem.
The documentation of <SID> right now is kind of opaque. I only kind of understand if after reading https://stackoverflow.com/questions/16768059/how-to-understand-these-vim-scripts and looking at this source code:
https://github.com/vim-scripts/a.vim/blob/master/plugin/a.vim
Describe the solution you'd like
Add some explicit examples of proper use of <SID>, so that someone who has a basic understanding of mappings and functions can input h: SID and understand it quickly.
Describe alternatives you've considered
Had to google some to find an answer.
Additional context
I'm an intermediate user. Whoever is reading this feature request is probably an advanced user who may not see how the documentation is opaque for intermediate users, but it is.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
lacygoill
Add some explicit examples of proper use of , so that someone who has a basic understanding of mappings and functions can input h: SID and understand it quickly.
You need <SID> if and only if:
- you have defined a function local to a script
- and now you want to call or evaluate that function in a context which is different from its script (where it was defined)
The latter bullet point is typically true when you call a function from a mapping (but not from a command installed with :command, nor from an autocmd installed with :autocmd).
Here is an example:
function s:Func() echomsg 'hello from s:Func' endfunction nnoremap <F3> :call <SID>Func()<CR>
Here, if you didn't write <SID> in the mapping, you would get an error when using it:
E81: Using <SID> not in a script context
Here are 2 other examples in mappings where the function is not simply called, but evaluated as an expression to be inserted or typed in normal mode:
function s:Func() return 'inserted from s:Func' endfunction inoremap <F3> <C-R>=<SID>Func()<CR> startinsert
function s:Func() echomsg "echo'ed from s:Func" return '' endfunction nnoremap <expr> <F3> <SID>Func()
Here is an example where the function is evaluated as an expression to replace some inserted text abc in insert mode, or the whole command-line in command-line mode:
function s:Func() return 'replaced from s:Func' endfunction inoreabbrev abc <C-R>=<SID>Func()<CR> startinsert
function s:Func() return 'replaced from s:Func' endfunction cnoremap <F3> <C-\>e <SID>Func()<CR>
Here is an example where the function is called to undo some options set by a filetype plugin:
function s:UndoFtplugin() return 'undone from s:UndoFtplugin' endfunction let b:undo_ftplugin = printf('call %sFunc()', expand('<SID>'))
And here is an example where the function is evaluated as an expression to set the status line:
function s:StatusLine() return 'from s:StatusLine' endfunction let &l:statusline = printf('%%!%sStatusLine()', expand('<SID>'))
Note that in the very first example, you don't need <SID> if you use <ScriptCmd>:
function s:Func() echomsg 'hello from s:Func' endfunction nnoremap <F3> <ScriptCmd>call s:Func()<CR>
And in Vim9 script, you don't even need s: (not even :call):
vim9script def Func() echomsg 'hello from Func' enddef nnoremap <F3> <ScriptCmd>Func()<CR>
Same thing for an <expr> mapping:
vim9script def Func(): string echomsg "echo'ed from Func" return '' enddef nnoremap <expr> <F3> Func()
With those examples, maybe you could suggest a patch to improve the help.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
ben.k...@gmail.com
Here is an example:
function s:Func() echomsg 'hello from s:Func' endfunction nnoremap <F3> :call <SID>Func()<CR>
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Bram Moolenaar
> On Sunday, February 26, 2023 at 6:48:16 PM UTC-5 lacygoill wrote:
>
> Here is an example:
> function s:Func() echomsg 'hello from s:Func' endfunction nnoremap <F3> :
> call <SID>Func()<CR>
>
> without trouble (_i.e._, it works). But you seem to be saying that `<SID>`
> is required… am I relying on a bug?
setting the script context of where the mapping was defined. Before
that using <SID> was required.
--
I'm in shape. Round IS a shape.
/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// \\\
\\\ sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///
Jordan Mandel
great examples!
When I posted this issue I hadn't found the documentation for in usr_41.txt; I think a good solution might be to just link to the relevant info from usr_41.txt (shortly after the PIECES heading).
If I were in charge I might include what you've written directly in the help for h: <SID>, but I think that the maintainers, who I imagine love terseness, might find it too verbose? I always go for verbosity/detail if it helps with understanding.
Another option would be to include a link from h: <SID> to the proper location in usr_41.txt which would be less verbose and also adequate.
As it stands I don't know enough about what changes to add to the repo to make the proper PR, but maybe someone reading this can do it before I figure it out!
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.