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

Re: Help with :help !

Expand Messages
  • Bram Moolenaar
    ... If you read the docs out-of-order you will miss some terms. If you don t know what a window is you really need to read part of the user manual first. ...
    Message 1 of 7 , Apr 1, 2006
    • 0 Attachment
      Bill Pursell wrote:

      > Benji Fisher wrote:
      > > You can help!
      > >
      > > This request is aimed at anyone on this list who has received
      > > valuable advice and wants to repay the vim community. That includes
      > > lurkers!
      > >
      > > Vim 7.0 has now started beta testing. One thing that
      > > non-developers, even newbies, can help with before the final release is
      > > improving the documentation.
      > >
      > <snip>
      >
      > After a total of 30 minutes playing with vim7, I decided to read through
      > the documentation on tabpage. 2 things I noticed:
      >
      > 1) The introduction begins with: "A tab page holds one or more
      > windows." At this point, it is not entirely clear what these words
      > mean. It might be nice to have a link from here (possibly on the words
      > "tab page" and the word "window") to something like the definitions of
      > the words "screen", "shell", and "window" that appear in the
      > documentation for design-decisions. This is perhaps not that
      > significant, but I think there is potential confusion.

      If you read the docs out-of-order you will miss some terms. If you
      don't know what a window is you really need to read part of the user
      manual first.

      > 2) he: tabdo Tabdo is listed in the documentation as not taking a !
      > argument, while windo does. I presume windo! {cmd} will process cmd
      > on all windows, regardless of any errors, but that's not stated in the
      > text. I notice that tabdo! is indeed not legal, and I'm curious to know
      > why. It would be handy if you could continue to process other tabs when
      > an error occurs. (Is that what the '!' on windo does?)

      Actually, :windo doesn't use the ! argument. It's only for :bufdo,
      which may need to close the current buffer, which fails if it was
      modified.

      There is no way for ":somedo" command to continue past an error, except
      putting your commands in a try/catch block.

      --
      A disclaimer for the disclaimer:
      "and before I get a huge amount of complaints , I have no control over the
      disclaimer at the end of this mail :-)" (Timothy Aldrich)

      /// Bram Moolenaar -- Bram@... -- http://www.Moolenaar.net \\\
      /// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
      \\\ download, build and distribute -- http://www.A-A-P.org ///
      \\\ help me help AIDS victims -- http://www.ICCF.nl ///
    • Bill Pursell
      ... I know what the terms mean. I m simply trying to point out that it may be useful to have a back reference at that point of the documentation. ... Then I
      Message 2 of 7 , Apr 1, 2006
      • 0 Attachment
        Bram Moolenaar wrote:
        > Bill Pursell wrote:
        >
        >
        >>Benji Fisher wrote:
        >>
        >>> You can help!
        >>>
        >>> This request is aimed at anyone on this list who has received
        >>>valuable advice and wants to repay the vim community. That includes
        >>>lurkers!
        >>>
        >>> Vim 7.0 has now started beta testing. One thing that
        >>>non-developers, even newbies, can help with before the final release is
        >>>improving the documentation.
        >>>
        >>
        >><snip>
        >>
        >>After a total of 30 minutes playing with vim7, I decided to read through
        >>the documentation on tabpage. 2 things I noticed:
        >>
        >>1) The introduction begins with: "A tab page holds one or more
        >>windows." At this point, it is not entirely clear what these words
        >>mean. It might be nice to have a link from here (possibly on the words
        >>"tab page" and the word "window") to something like the definitions of
        >>the words "screen", "shell", and "window" that appear in the
        >>documentation for design-decisions. This is perhaps not that
        >>significant, but I think there is potential confusion.
        >
        >
        > If you read the docs out-of-order you will miss some terms. If you
        > don't know what a window is you really need to read part of the user
        > manual first.
        >

        I know what the terms mean. I'm simply trying to point out that it may
        be useful to have a back reference at that point of the documentation.

        >>2) he: tabdo Tabdo is listed in the documentation as not taking a !
        >>argument, while windo does. I presume windo! {cmd} will process cmd
        >>on all windows, regardless of any errors, but that's not stated in the
        >>text. I notice that tabdo! is indeed not legal, and I'm curious to know
        >>why. It would be handy if you could continue to process other tabs when
        >>an error occurs. (Is that what the '!' on windo does?)
        >
        >
        > Actually, :windo doesn't use the ! argument. It's only for :bufdo,
        > which may need to close the current buffer, which fails if it was
        > modified.

        Then I would suggest that the documentation for windo not specify an
        optional !. Either that, or tabdo do should allow it (and ignore it)
        the same way windo does. The documentation and behavior should be
        consistent.
      • Gary Johnson
        ... 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
        Message 3 of 7 , Apr 2, 2006
        • 0 Attachment
          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
          "user-manual".

          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

          --
          Gary Johnson | Agilent Technologies
          garyjohn@... | Wireless Division
          | Spokane, Washington, USA
        Your message has been successfully submitted and would be delivered to recipients shortly.