Thanks for the work on this, Christian! It's a good breakdown of various ways to navigate the help. A few grammar fixes, nitpicks, and suggestions below.
On Sat, Jan 09, 2016 at 09:27:22PM +0100, Christian Brabandt wrote: > 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 Unnecessary comma after "advantage". > +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 Unnecessary comma after "know". > + options.txt to open the help page which describes all option handling > + and then you can search using regular expressions e.g. textwidth s/you can //; s/ e.g..*/,&./ > + 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). Some indication that "letter" isn't literal in these examples would be good. I had to double check that "cpo-letter" wasn't a help topic. Later on, you seem to have taken the tack of enclosing them in <>, so maybe cpo-<letter> and go-<letter>, along with an example for clarity. > +2) normal mode commands are just that. Use :h |gt| to go to the help page Capitalize "normal" > + for the "gt" command > + > +3) regexp items always start with / So :h |/\+| takes you to the help item Capitalize "regexp" > + for the "\+" quantifier in Vim regexes. If you need to know anything Maybe s/anything/everything/ ? > + 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. Again, somehow indicating that Letter isn't literal would be useful. > + 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 Why not use ": instead of quote: ? Hmm, seems like Vim internally does a translation, since ": isn't actually in the file, but is accepted. > + the special ":" register. > + > +6) Vim Script (VimL) is available at :h |eval.txt| Certain aspects of the Missing period after |eval.txt|. > + 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 "is" after important would be a little smoother. > + 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 Missing period after |map.txt|. > + |mapmode-i| to find out about |:imap| command. Also use :map-topic to s/about/& the/ > + 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 definition -> definitions Comma after "command-topic". > + :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. command -> commands > +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 Capitalize "use" > + available topics |c_CTRL-D| > + > +12) |:helpgrep| to search in the entire help pages (and also of any s/the entire/all/ > + 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 s/there to/there too/, I think. The sentence is a little unwieldy. Maybe break it into a couple sentences instead of a long parenthetical. > + 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). I would reword this last sentence a little. Maybe: Skim over the contents to find interesting topics. The "Digraphs" and "Entering special characters" items are 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. Capitalize "highlighting" > + :h |hl-WarningMsg| talks about the WarningMsg highlighting group > + > +16) syntax highlighting is namespaced to :syn-topic e.g. :h |:syn-conceal| Capitalize "syntax" > + talks about the conceal argument for the :syn command. > + > +17) quickfix commands usually start with :c while location list commands Capitalize "quickfix" > + usually start with :l > + > +18) :h |BufWinLeave| talks about the BufWinLeave auto command. Also autocommand is one word. > + :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. I would be consistent in terminology here. You start with the term "Startup arguments" but then call -f a command switch. I think "command-line switch" is good. > +20) compiled extra features always start with "+" so :h |+conceal| Capitalize "compiled" > + talks about the conceal support > + > +21) Also a link to the user documentation (which describes certain Remove "Also" > + 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. The above should probably be generalized to something along the lines of "Documentation for filetype specific functionality is usually available in the form ft-<filetype>-<functionality>." > +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 > > > ============================================================================== > -- James GPG Key: 4096R/331BA3DB 2011-12-05 James McCoy <[email protected]> -- -- 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.
