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

Re: Help with :help !

Expand Messages
  • Eric Arnold
    ... 1. Introduction *windows-intro* A window is a viewport onto a buffer. You can use multiple windows on one buffer, or several windows on different
    Message 1 of 7 , Apr 1, 2006
    • 0 Attachment
      --- Bill Pursell <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.

      :help windows

      1. Introduction *windows-intro*

      A window is a viewport onto a buffer. You can use multiple windows on one
      buffer, or several windows on different buffers.

      A buffer is a file loaded into memory for editing. The original file remains
      unchanged until you write the buffer to the file.



      If you haven't figured out :help window^D to expand all possible
      completions, then you need to staple it into your bag of tricks. It's on the
      first :help page, but until you use it some, it's [huge] value isn't
      obvious.

      I think the help doc.s lead you through the concepts pretty well. If you don't
      have the patience (i.e. me) to go through the doc.s as they are designed, then
      it is up to you to handle the fragmented information stream into your brain.

      There are also GUI windows, which refer to the whole running instance. This
      makes sense in the context of the X11 or MSwin envs.

      A shell doesn't really belong in the same category as the others. It refers to
      the shell (i.e. sh/csh/etc) that Vim uses to start something outside itself.

      >[...]
      >
      > Also, I'm not sure if this is a result of an improper install (I
      > downloaded from the cvs, used 'vim -c make' to build, set VIMRUNTIME to
      > the resultant runtime dir, and executed via "vim -u NONE"), but I no
      > longer have any history in command mode, and I can't use <CTRL>f to
      > enter the command window.
      >

      Umm, that's because you lost the "history" option by using -u NONE, among other
      things. Getting all those options set (probably for ^f also) is non-trivial,
      that's why -u NONE is such a pain.
    • Eric Arnold
      The Vim7 sections I have had trouble with so far are for the tabline and the new List and Dictionary support. The examples have errors in them, ranging from
      Message 2 of 7 , Apr 1, 2006
      • 0 Attachment
        The Vim7 sections I have had trouble with so far are for the "tabline" and the
        new List and Dictionary support. The examples have errors in them, ranging
        from missing "let" commands before setting variables, to more subtle stuff.

        It would have been better for the example for a "tabline" function to be a
        working template. I have just written a more detailed script. I wasn't able
        to find a .vim file delivered with the runtime stuff that is responsible for
        the default tabline behaviour. Is it internal, or did I miss something? It
        would be nice to have the default accessible, and perhaps a few alternatives
        (like colorschemes, etc.).

        The explanations of how failures manifest in the world of lists and dicts
        should be extended. It's pretty easy (for me anyway) to get yourself into a
        mess where you are frazzled trying to track down "type mismatch" errors (I
        posted about this maddness earlier). I can't say whether the lists and dicts
        will mature, and be completely robust about handling foolish invocations, but a
        trouble shooting section would be helpful in any case.



        --- Bill Pursell <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>
      • 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 3 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 4 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 5 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.