Hi Bram! On Sa, 09 Jan 2016, Bram Moolenaar wrote:
> > Christian Brabandt wrote: > > > here is a patch, that documents, how to use the help. I have written > > down this in the vim-use ml and thought it would be useful to have in > > the help itself. > > > > https://groups.google.com/d/msg/vim_use/2ZKTBdhsBC4/hETpTMnEAQAJ > > https://groups.google.com/d/msg/vim_use/2ZKTBdhsBC4/uaDrb15LAgAJ > > We already have the explanation at ":help". But it's quite short. > I don't think this is the right place for a long explanation. > > There is also ":help help-summary" in the user manual. I think that's a > better place to merge in what you wrote. I don't find the current list > there very useful. > > Then add a reference from ":help". Updated patch attached Best, Christian -- Gegen wen ich denke? Gegen diejenigen, die es mir verbieten. -- Stanislaw Jerzy Lec (eig. S. J. de Tusch-Letz) -- -- You received this message from the "vim_dev" maillist. Do not top-post! Type your reply below the text you are replying to. For more information, visit http://www.vim.org/maillist.php --- You received this message because you are subscribed to the Google Groups "vim_dev" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 64de957..f1449ed 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -25,6 +25,7 @@ Get specific help: It is possible to go directly to whatever you want help Vim command argument - :help -r Option ' :help 'textwidth' Regular expression / :help /[ + Learn to use the help: ":help |help-summary|" Search for help: Type ":help word", then hit CTRL-D to see matching help entries for "word". Or use ":helpgrep word". |:helpgrep| diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index da63640..e430902 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -498,66 +498,136 @@ You can use the error ID at the start to find help about it: > :help E37 -Summary: *help-summary* > - :help -< Gives you very general help. Scroll down to see a list of all - helpfiles, including those added locally (i.e. not distributed - with Vim). > - :help user-toc.txt -< Table of contents of the User Manual. > - :help :subject -< Ex-command "subject", for instance the following: > - :help :help -< Help on getting help. > - :help abc -< normal-mode command "abc". > - :help CTRL-B -< Control key <C-B> in Normal mode. > - :help i_abc - :help i_CTRL-B -< The same in Insert mode. > - :help v_abc - :help v_CTRL-B -< The same in Visual mode. > - :help c_abc - :help c_CTRL-B -< The same in Command-line mode. > - :help 'subject' -< Option 'subject'. > - :help subject() -< Function "subject". > - :help -subject -< Command-line argument "-subject". > - :help +subject -< Compile-time feature "+subject". > - :help /* -< Regular expression item "*" > - :help EventName -< Autocommand event "EventName". > - :help digraphs.txt -< The top of the helpfile "digraph.txt". - Similarly for any other helpfile. > - :help pattern<Tab> -< Find a help tag starting with "pattern". Repeat <Tab> for - others. > - :help pattern<Ctrl-D> -< See all possible help tag matches "pattern" at once. > - :helpgrep pattern -< Search the whole text of all help files for pattern "pattern". - Jumps to the first match. Jump to other matches with: > - :cn -< next match > - :cprev - :cN -< previous match > - :cfirst - :clast -< first or last match > - :copen - :cclose -< open/close the quickfix window; press <Enter> to jump - to the item under the cursor - + *help-summary* +If you know what you are looking for, it is usually easier to search for it +using the help system, instead of using google. Because the subjects follow +a certain style guide. + +Also the help has the advantage, of belonging to your particular vim +version (well, usually), so that obsolete topics or topics that have +been added later won't turn up. + +Therefore, it is essential to learn the help system and the language it +uses. Here are some hints on how to use the help: + +1) Options generally are enclosed in single apostrophes. So you would + use :h 'list' to go to the help topic for the list option. If you + only know, you are looking for a certain option, you can also do :h + options.txt to open the help page which describes all option handling + and then you can search using regular expressions e.g. textwidth + Certain options have their own namespace, e.g. :h cpo-letter (for the + corresponding flag of the 'cpoptions' settings) or :h go-letter (for + the guioption flags). + +2) normal mode commands are just that. Use :h |gt| to go to the help page + for the "gt" command + +3) regexp items always start with / So :h |/\+| takes you to the help item + for the "\+" quantifier in Vim regexes. If you need to know anything + about regular expressions, start reading at :h |pattern.txt| + +4) Key combinations. They usually start with a single letter indicating + the mode for which they can be used. E.g. :h |i_CTRL-X| takes you to + the family of Ctrl-X commands for insert mode which can be used to + auto complete different things. Note, that certain keys will always + be written the same, e.g. Control will always be CTRL. + Note, for normal mode commands, the "n" is left away and the topic is + available at :h CTRL-Letter. + In contrast :h |c_CTRL-R| will describe what the Ctrl-R does when + entering commands in the Command line and :h |v_Ctrl-A| talks about + incrementing numbers in visual mode and :h |g_CTRL-A| talks about the + g<C-A> command (e.g. you have to press "g" then <Ctrl-A>). Here the + "g" stand for the normal command "g" which always expects a second key + before doing something similar to the commands starting with "z" + +5) Registers always start with quote so use :h |quote:| to find out about + the special ":" register. + +6) Vim Script (VimL) is available at :h |eval.txt| Certain aspects of the + language are available at :h expr-X where "X" is a single letter, + e.g. :h |expr-!| will take you to the topic describing the "!" (Not) + operator for VimScript. + Also important :h |function-list| to find a short description of all + functions available. Also help topics for VimL functions always + include the "()", :h |append()| talks about the append VimL function + rather than how to append text in the current buffer. + +7) Mappings are talked about in the help page :h |map.txt| Use :h + |mapmode-i| to find out about |:imap| command. Also use :map-topic to + find out about certain subtopics particular for mappings (e.g. :h + |:map-local| for buffer-local mappings or |map_bar| for how the '|' is + handled in mappings. + +8) Command definition are talked about :h command-topic so use + :h |command-bar| to find out about the '!' argument for custom + commands. + +9) Window management commands always start with CTRL-W, so you find the + corresponding help at :h CTRL-W_letter (e.g. |CTRL-W_p| for moving the + previous accessed window). You can also access :h |windows.txt| and + read your way through if you are looking for window handling command. + +10) Ex-commands always start with ":", so :h |:s| covers the :s command + +11) use Ctrl-D after typing a topic and let Vim try to complete to all + available topics |c_CTRL-D| + +12) |:helpgrep| to search in the entire help pages (and also of any + installed plugins). See :h |:helpgrep| for how to use it. + Once you have searched for a topic, all matches are available in the + quickfix (or locationlist) window which can be opened with |:copen| or + |:lopen|. You can search there to (so you could search there for + options.txt to only find matches that talk about options and + settings). + +13) :h |helphelp| contains some information on how to use the help. + +14) The user manual. This describes help topics for beginners in a + rather friendly way. Start at :h |usr_toc.txt| to find the table of + content (as you might have guessed). Skimming over that help finding + certain topics, .e.g you will find an entry "Digraphs" and "Entering + special characters" in chapter 24 (so use :h |usr_24.txt| to go to + that particular help page). Also if you want to access a certain + chapter in the help, the chapter number can be accessed directly + like this: :h |10.1| (goes to chapter 10.1 in |usr_10.txt| and + talks about recording macros) + +15) highlighting groups. Always start with hl-groupname. E.g. + :h |hl-WarningMsg| talks about the WarningMsg highlighting group + +16) syntax highlighting is namespaced to :syn-topic e.g. :h |:syn-conceal| + talks about the conceal argument for the :syn command. + +17) quickfix commands usually start with :c while location list commands + usually start with :l + +18) :h |BufWinLeave| talks about the BufWinLeave auto command. Also + :h |autocommands-events| talks about all possible events. + +19) Startup arguments always start with "-" So :h |-f| takes you to the + help of the -f command switch of Vim. + +20) compiled extra features always start with "+" so :h |+conceal| + talks about the conceal support + +21) Also a link to the user documentation (which describes certain + commands more from a user perspective and less detailed) will be + mentioned at the top of help pages if they are available. So + :h |pattern.txt| mentions the user guide topics |03.9| and |27| + +22) Documentation for included syntax files is usually available at + :h ft-<filetype>-syntax. + So :h |ft-c-syntax| talks about the C syntax file and the option + it provides. Sometimes, additional sections for omni completion + (:h |ft-php-omni|) or filetype plugins (:h |ft-tex-plugin|) are + available. + +23) Error and Warning codes can be looked up directly in the help. So + :h |E297| takes you exactly to the description of the swap error message + and :h |W10| talks about the warning "Changing a readonly file". + Sometimes however, those error codes are not described, but + rather are listed at the vim command, that usually causes this. + So |E128| takes you directly to the |:function| command ==============================================================================
