Loading ...
Sorry, an error occurred while loading the content.

67199Re: Help with :help !

Expand Messages
  • Gary Johnson
    Apr 2, 2006
      On 2006-03-30, Benji Fisher <benji@...> wrote:

      > Do not neglect the users' manual:
      > :help toc

      One issue with the :help for Vim-7.0 is that that command doesn't
      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
    • Show all 7 messages in this topic