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

Re: Help with :help !

Expand Messages
  • 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 1 of 7 , Apr 1 12:50 AM
    View Source
    • 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 2 of 7 , Apr 1 3:04 AM
      View Source
      • 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 3 of 7 , Apr 1 3:18 AM
        View Source
        • 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 4 of 7 , Apr 1 4:31 AM
          View Source
          • 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 5 of 7 , Apr 1 9:19 AM
            View Source
            • 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 6 of 7 , Apr 2 1:08 PM
              View Source
              • 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.