67199Re: Help with :help !
- Apr 2, 2006On 2006-03-30, Benji Fisher <benji@...> wrote:
> Do not neglect the users' manual:One issue with the :help for Vim-7.0 is that that command doesn't
> :help toc
take you where it used to. It now takes you to the Reference Manual
table of contents rather than the User Manual table of contents.
This is going to confuse people who, out of habit, type ":help toc"
to get to the User Manual. It's also going to confuse people who
have been told by more experienced users on the vim list and on
comp.editors to use ":help toc" to get to the User Manual and
probably have that command written on a crib sheet. For those
reasons, I would suggest adding just "toc" to the tags for the User
Manual table of contents.
Further, there is an inconsistency between the tags used for the two
tables of contents. Since ":help toc" takes you to "ref-toc", upon
realizing your mistake, you might think that ":help user-toc" or
":help usr-toc" would take you where you want to go. Wrong. The
tag for the User Manual table of contents is "usr_toc.txt" or
This illustrates the difference between "readability" and
"searchability" or "learnabilty". Any of those tags looks
reasonable when you at it. However, seeing one does not give you
reliable cues for finding the others.
Solving that problem properly would require developing a style for
Vim tags that might include rules for constructing abbreviations and
when to use them (e.g., "usr" vs. "user") and for combining words
with '-' vs. '_' vs. just running the words together.
I'm not sure how far we or Bram want to take that, but one editing
task ought to be checking for the more obvious inconsistencies such
as the toc tags.
Gary Johnson | Agilent Technologies
garyjohn@... | Wireless Division
| Spokane, Washington, USA
- << Previous post in topic