And this time with an actual attachment. On Fr, 08 Jan 2016, Christian Brabandt wrote:
> Bram, > 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 Mit freundlichen Grüßen Christian -- Tiere sind meine Freunde, und ich esse meine Freunde nicht. -- George Bernard Shaw -- -- 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/helphelp.txt b/runtime/doc/helphelp.txt index 4ef436c..9bd8d84 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -9,6 +9,7 @@ Help on help files *helphelp* 1. Help commands |online-help| 2. Translated help files |help-translated| 3. Writing help files |help-writing| +4. Using the help files |help-usage| ============================================================================== 1. Help commands *online-help* @@ -351,4 +352,137 @@ highlighting. So do these: You can find the details in $VIMRUNTIME/syntax/help.vim +============================================================================== +4. Using the help *help-usage* + +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. User :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 + vim:tw=78:ts=8:ft=help:norl:
