How to Interpret Syntax in VIM Help Pages

Question

I have difficulty understanding syntax provided in man pages. I realize that the syntax is trying to tell me the range of things you can do, but I often can't distinguish between characters that are "needed while writing the command" and "characters that only have syntactical meaning". I often end up writing commands that don't work because I've included syntax in the command that shouldn't be there.

I'm not looking for an explanation of only one concrete example. I'm looking for a resource that lists all symbols used and their meanings.

For example, I've gathered that stuff that's [inside brackets like this] seems to mean optional, but sometimes I suspect the [ and ] are meant literally too. Another example is { and } in something like :[range]m[ove] {address}. I'm not sure what those curly brackets mean. Are they required in the command or not? Is there some standard I can read that explains how to interpret not only these symbols, but all symbols uses throughout the documentation?

I tried :help syntax in hopes that there was a help page explaining how to interpret the syntax used throughout the vim help pages, but this produced information on "Syntax Highlighting".

Can you direct me to a resource that explains the syntax itself?

Answer 1

The basic help syntax being used is (of course) being explained in the help system itself.

You can find it (in the not so easy discoverable) help tag :h notation. Copying it here for reference:

4. Notation                                             notation

When syntax highlighting is used to read this, text that is not typed
literally is often highlighted with the Special group.  These are items in [],
{} and <>, and CTRL-X.

Note that Vim uses all possible characters in commands.  Sometimes the [], {}
and <> are part of what you type, the context should make this clear.

[]              Characters in square brackets are optional.

                                                    count [count]
[count]         An optional number that may precede the command to multiply
                or iterate the command.  If no number is given, a count of one
                is used, unless otherwise noted.  Note that in this manual the
                [count] is not mentioned in the description of the command,
                but only in the explanation.  This was done to make the
                commands easier to look up.  If the 'showcmd' option is on,
                the (partially) entered count is shown at the bottom of the
                window.  You can use <Del> to erase the last digit (N<Del>).

                                                        [quotex]
["x]            An optional register designation where text can be stored.
                See registers.  The x is a single character between 'a' and
                'z' or 'A' and 'Z' or '"', and in some cases (with the put
                command) between '0' and '9', '%', '#', or others.  The
                uppercase and lowercase letter designate the same register,
                but the lowercase letter is used to overwrite the previous
                register contents, while the uppercase letter is used to
                append to the previous register contents.  Without the ""x" or
                with """" the stored text is put into the unnamed register.

                                                        {}
{}              Curly braces denote parts of the command which must appear,
                but which can take a number of different values.  The
                differences between Vim and Vi are also given in curly braces
                (this will be clear from the context).

                                                        {char1-char2}
{char1-char2}   A single character from the range char1 to char2.  For
                example: {a-z} is a lowercase letter.  Multiple ranges may be
                concatenated.  For example, {a-zA-Z0-9} is any alphanumeric
                character.

                                                {motion} movement
{motion}        A command that moves the cursor.  These are explained in
                motion.txt.  Examples:
                        w               to start of next word
                        b               to begin of current word
                        4j              four lines down
                        /The<CR>        to next occurrence of "The"
                This is used after an operator command to move over the text
                that is to be operated upon.
                - If the motion includes a count and the operator also has a
                  count, the two counts are multiplied.  For example: "2d3w"
                  deletes six words.
                - The motion can be backwards, e.g. "db" to delete to the
                  start of the word.
                - The motion can also be a mouse click.  The mouse is not
                  supported in every terminal though.
                - The ":omap" command can be used to map characters while an
                  operator is pending.
                - Ex commands can be used to move the cursor.  This can be
                  used to call a function that does some complicated motion.
                  The motion is always characterwise exclusive, no matter
                  what ":" command is used.  This means it's impossible to
                  include the last character of a line without the line break
                  (unless 'virtualedit' is set).
                  If the Ex command changes the text before where the operator
                  starts or jumps to another buffer the result is
                  unpredictable.  It is possible to change the text further
                  down.  Jumping to another buffer is possible if the current
                  buffer is not unloaded.

                                                        {Visual}
{Visual}        A selected text area.  It is started with the "v", "V", or
                CTRL-V command, then any cursor movement command can be used
                to change the end of the selected text.
                This is used before an operator command to highlight the
                text that is to be operated upon.
                See Visual-mode.

                                                        <character>
<character>     A special character from the table below, optionally with
                modifiers, or a single ASCII character with modifiers.

                                                        'character'
'c'             A single ASCII character.

                                                        CTRL-{char}
CTRL-{char}     {char} typed as a control character; that is, typing {char}
                while holding the CTRL key down.  The case of {char} does not
                matter; thus CTRL-A and CTRL-a are equivalent.  But on some
                terminals, using the SHIFT key will produce another code,
                don't use it then.

                                                        'option'
'option'        An option, or parameter, that can be set to a value, is
                enclosed in single quotes.  See options.

                                                        quotecommandquote
"command"       A reference to a command that you can type is enclosed in
                double quotes.
command       New style command, this distinguishes it from other quoted
                text and strings.
[...]

The help page continues with the :h key-notation which is again a worthwhile read on how keynames are used inside Vims help pages, especially when trying to map keys.

I also just sent in a small doc-patch, to make this help-entry more easily discoverable from the main help page.