I feel compelled to articulate some difficulties I had with neovim :help back in the day.
The :help system in neovim is excellent in that it covers an extensive range
of topics.
By default, :help or :help <term> opens in a horizontal split.
Not the best experience.
While it is true that this behavior can be customized thoroughly, a new user
isn’t going to have the requisite knowledge to do so.
Not without consulting the very help buffers that are being spawned so
awkwardly.
Possible alternatives?
How about a vertical split, or opening the help buffer in a new tab?
These options may have their disadvantages,
but offer some benefits to the reader.
They are easier to read,
in that more help text fits in the buffer.
:hori help is the default but can be hard to read and is wasteful with terminal width.
:vert help some users prefer this, but it can render poorly depending on terminal width.
:tab help provides ample space for help text, but the user must know how to navigate tabs.
Whatever method is used,
the goal should be to encourage the reader to consult the help manual.
Go head, try :help in a default environment.
Though difficult, imagine looking at this as a new user.
What is important on this page?
How large is this page?
Do I need to read all of it?
If there are links to another page, what will happen if I select it?
The following render is what I see when :help is called.
It does a good job of highlighting basic movement and how to exit the window.
However, there are important details missing due to the orientation of the split.
default :help window
help.txt Nvim
NVIM - help
k
Move around: Use the cursor keys, or "h" to go left, h l
"j" to go down, "k" to go up, "l" to go right. j
Close this window: Use ":q<Enter>".
Get out of Vim: Use ":qa!<Enter>" (careful, all changes are lost!).
Jump to a subject: Position the cursor on a tag (e.g. bars) and hit CTRL-].
With the mouse: Double-click the left mouse button on a tag, e.g. bars.
Jump back: Type CTRL-O. Repeat to go further back.
Get specific help: It is possible to go directly to whatever you want help
on, by giving an argument to the :help command.
Prepend something to specify the context: help-context
WHAT PREPEND EXAMPLE
Normal mode command :help x
Visual mode command v_ :help v_u
Insert mode command i_ :help i_<Esc>
Command-line command : :help :quit
Command-line editing c_ :help c_<Del>
Vim command argument - :help -r
Option ' :help 'textwidth'
Regular expression / :help /[
See help-summary for more contexts and an explanation.
help.txt [Help][RO] 1,8 Top
True, we can’t show everything in a single buffer page.
And terminal size will vary the contents.
But a vertical split does a better job here.
I get :helpgrep and :vimtutor mentions on the first page on my machine
with a vertical split.
There is also a good chunk of the reference table of contents.
If you have been using this $EDITOR for a significant amount of time, these details
probably don’t matter. For the new user this can be the difference
between a good first impression of the help system, and a not so good one.
vertical split :help window
help.txt Nvim
NVIM - help
k
Move around: Use the cursor keys, or "h" to go left, h l
"j" to go down, "k" to go up, "l" to go right. j
Close this window: Use ":q<Enter>".
Get out of Vim: Use ":qa!<Enter>" (careful, all changes are lost!).
Jump to a subject: Position the cursor on a tag (e.g. bars) and hit CTRL-].
With the mouse: Double-click the left mouse button on a tag, e.g. bars.
Jump back: Type CTRL-O. Repeat to go further back.
Get specific help: It is possible to go directly to whatever you want help
on, by giving an argument to the :help command.
Prepend something to specify the context: help-context
WHAT PREPEND EXAMPLE
Normal mode command :help x
Visual mode command v_ :help v_u
Insert mode command i_ :help i_<Esc>
Command-line command : :help :quit
Command-line editing c_ :help c_<Del>
Vim command argument - :help -r
Option ' :help 'textwidth'
Regular expression / :help /[
See help-summary for more contexts and an explanation.
See notation for an explanation of the help syntax.
Search for help: Type ":help word", then hit CTRL-D to see matching
help entries for "word".
Or use ":helpgrep word". :helpgrep
Getting started: Do the Vim tutor, a 30-minute interactive course for the
basic commands, see vimtutor.
Read the user manual from start to end: usr_01.txt
Vim stands for Vi IMproved. Most of Vim was made by Bram Moolenaar, but only
through the help of many others. See credits.
==============================================================================
NVIM DOCUMENTATION
------------------------------------------------------------------------------
ABOUT NVIM reference_toc doc-file-list Q_ct
news News since the previous release
nvim Transitioning from Vim
vim-differences Nvim compared to Vim
faq Frequently Asked Questions
user-manual User manual: How to accomplish editing tasks.
quickref Overview of common commands
tutor 30-minute interactive course for beginners
copying About copyrights
iccf Helping poor children in Uganda
help.txt [Help][RO] 1,1 Top
The neovim documentation doesn’t provide examples of usage for many of its lua functions.
The details of the function signature are explained,
but often we do not get an example of the function being used.
This can lead to a misunderstanding of the syntax.
When the user can’t grok how to call even the most basic functions,
this can stall forward progress.
There are certainly plugins and other resources that can help with explaining
documentation, but these shouldn’t be required.
One minor pet peeve of mine is when the explanation for one function references another,
which then reciprocates.
the explaination directs reader to another function... ok
nvim_command({command}) *nvim_command()*
Executes an Ex command.
On execution error: fails with Vimscript error, updates v:errmsg.
Prefer |nvim_cmd()| or |nvim_exec2()| instead. To modify an Ex command in
a structured way before executing it, modify the result of
|nvim_parse_cmd()| then pass it to |nvim_cmd()|.
Attributes: ~
Since: 0.1.0
Parameters: ~
• {command} Ex command string
the destination references the original function
nvim_cmd({cmd}, {opts}) *nvim_cmd()*
Executes an Ex command.
Unlike |nvim_command()| this command takes a structured Dict instead of a
String. This allows for easier construction and manipulation of an Ex
command. This also allows for things such as having spaces inside a
command argument, expanding filenames in a command that otherwise doesn't
expand filenames, etc. Command arguments may also be Number, Boolean or
String.
Neither explanation shows the user how to use this thing, or a situation where
the user might want to.
An example would show correct usage of the function, and also show
what an “Ex command” is if the user wasn’t already familiar with the term.
The explanation for nvim_cmd() does a lot of telling, when showing would go a
long way to demonstrate its advantages over nvim_command().
some function do indeed have examples, hooray!
nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
Prints a message given by a list of `[text, hl_group]` "chunks".
Example:
vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
discovering the nvim_echo() entry, was helpful!
If the user doesn’t know about the function they might needlessly struggle,
trying to call echo via nvim_command().
Depending on the string(s), the user might not have a fun time.
Don’t ask me why I know this.