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

Help with :help !

Expand Messages
  • Benji Fisher
    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
    Message 1 of 7 , Mar 30 8:33 AM
    • 0 Attachment
      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.

      :help design-documented

      There are many new features, and sometimes during development the docs
      and the code are not kept in sync. Sometimes a new feature makes old
      docs obsolete. (Search for "there is no way to ...")

      I would love it if a bunch of users each adopted one section of the
      docs. Maybe a whole file, like doc/pattern.txt . Maybe just part of
      such a file, like the section corresponding to

      1. Search commands |search-commands|

      Test the examples, look for mistakes. Suggest better wording if things
      are unclear, and correct typos. Suggest new help tags so that others
      can find what they need. Learn more about how vim works, so that you
      become a vim guru!

      If something is unclear, and you are not sure how to correct it,
      ask for help.

      If you plan to adopt one section of the docs, please mention it on
      this thread so that others will focus on different parts of the docs.

      Do not neglect the users' manual:

      :help toc

      --Benji Fisher

      P.S. Another way to repay the vim community is to post a vim tip when
      someone on the list solves a problem for you. It is OK (IMHO) if you
      post something that is not your idea, as long as you give credit.

      http://www.vim.org/tips/index.php
    • Bill Pursell
      ... 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
      Message 2 of 7 , Apr 1, 2006
      • 0 Attachment
        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.

        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?)

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