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

Proposed bugfix for help

Expand Messages
  • Antoine J. Mechelynck
    From: Antoine J. Mechelynck To: bram@moolenaar.net (recipient for action) Cc: vim@vim.org (recipients for info) Bug: Code
    Message 1 of 3 , May 1 12:40 AM
    • 0 Attachment
      From: "Antoine J. Mechelynck" < antoine.mechelynck@... >
      To: bram@... (recipient for action)
      Cc: vim@... (recipients for info)

      Bug: Code examples given in help should in many cases go through all the
      directories in 'runtimepath' rather than only $VIMRUNTIME.

      Fix: Replace (where needed) ":source $VIMRUNTIME/" by ":runtime! "

      NB: I constructed the following "patch" by hand, using helpgrep but not
      diff. Its format might be slightly different from what your patch program
      expects. My distribution is 6.2.494, which is recent, but not quite the
      latest, so in some cases you might have to adjust line numbers slightly.
      Also, even though I pasted via the clipboard, OE6 may have replaced tabs by
      spaces in a not-very-consistent way. Conventions:

      *** filename.txt (datestamp) for Vim 6.2. (All files are in
      $VIMRUNTIME/doc/).

      --- nnn --- : remove line nnn, which should be the following
      --- nnn-mmm --- : remove lines nnn to mmm (inclusive), which should be the
      following

      +++ nnn +++ : add the following as the new line nnn
      +++ nnn-mmm +++ : add the following as the new lines nnn-mmm

      Changes to the datestamps in line 1 of all changed files are not mentioned.

      ----- start -----
      *** filetype.txt (2004 Jan 17) for Vim 6.2
      --- 262 ---
      :au BufRead *.html,<&faf;HTML> so $VIMRUNTIME/syntax/html.vim
      +++ 262 +++
      :au BufRead *.html,<&faf,HTML> runtime! syntax/html.vim
      *** gui.txt (2004 Apr 02) for Vim 6.2
      --- 470 ---
      :source $VIMRUNTIME/menu.vim
      +++ 470 +++
      :runtime! menu.vim
      *** lang.txt (2004 Feb 24) for Vim 6.2
      --- 100-101 ---
      have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", where "xx" is the
      abbreviation of the language (mostly two letters).
      +++ 100-102 +++
      have to be placed in "<directory>/lang/xx/LC_MESSAGES", where "xx" is the
      abbreviation of the language (mostly two letters) and <directory> is one of
      the
      directories in 'runtimepath'.
      *** mlang.txt (2004 Feb 24) for Vim 6.2
      --- 178-182 ---
      To try out your translations you first have to remove all menus. This is
      how
      you can do it without restarting Vim: >
      :source $VIMRUNTIME/delmenu.vim
      :source <your-new-menu-file>
      :source $VIMRUNTIME/menu.vim
      +++ 178-182 +++
      To try out your translations you first have to remove all menus. This is
      how
      you can do it without restarting Vim (assuming your menu is called menu.vim
      and is placed in a directory mentioned in 'runtimepath'): >
      :source $VIMRUNTIME/delmenu.vim
      :runtime! menu.vim
      *** options.txt (2004 Apr 18) for Vim 6.2
      --- 3740-3744 ---
      this option has no effect. But you could do this: >
      :source $VIMRUNTIME/delmenu.vim
      :set langmenu=de_DE.ISO_8859-1
      :source $VIMRUNTIME/menu.vim
      < Warning: This deletes all menus that you defined yourself!
      +++ 3740-3743 +++
      this option has no effect. But you could do this: >
      :source $VIMRUNTIME/delmenu.vim
      :set langmenu=de_DE.ISO_8859-1
      :runtime! menu.vim
      *** syntax.txt (2004 Mar 26) for Vim 6.2
      --- 54-55 ---
      What this command actually does is to execute the command >
      :source $VIMRUNTIME/syntax/syntax.vim
      +++ 54-55 +++
      What this command actually does is to execute the command >
      :runtime! syntax/syntax.vim
      --- 131-137 ---
      for example, the cpp.vim file could include the c.vim file: >
      :so $VIMRUNTIME/syntax/c.vim

      The .vim files are normally loaded with an autocommand. For example: >
      :au Syntax c source $VIMRUNTIME/syntax/c.vim
      :au Syntax cpp source $VIMRUNTIME/syntax/cpp.vim
      These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.
      +++ 131-137 +++
      for example, the cpp.vim file could include the c.vim file: >
      :runtime! syntax/c.vim

      The .vim files are normally loaded with an autocommand. For example: >
      :au Syntax c runtime! syntax/c.vim
      :au Syntax cpp runtime! syntax/cpp.vim
      These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.
      --- 279 ---
      +- Source $VIMRUNTIME/syntax/synload.vim from 'runtimepath'
      +++ 279 +++
      +- Source syntax/synload.vim from 'runtimepath'
      *** usr_01.txt (2003 Jan 12) for Vim 6.2
      --- 61-72 ---
      setup, copy the example vimrc file. By doing this inside Vim you don't have
      to check out where it is located. How to do this depends on the system you
      are using:

      Unix: >
      :!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc
      MS-DOS, MS-Windows, OS/2: >
      :!copy $VIMRUNTIME/vimrc_example.vim $VIM/_vimrc
      Amiga: >
      :!copy $VIMRUNTIME/vimrc_example.vim $VIM/.vimrc

      If the file already exists you probably want to keep it.
      +++ 61-66 +++
      setup, include the example vimrc file. An easy way to do this is to have the
      line: >
      runtime vimrc_example.vim

      near the start of your vimrc. Place your own preferences after that, so they
      override the defaults, and not vice-versa.
      *** usr_12.txt (2004 Jan 17) for Vim 6.2
      --- 249 ---
      :source $VIMRUNTIME/ftplugin/man.vim
      +++ 249 +++
      :runtime! ftplugin/man.vim
      *** usr_45.txt (2002 Oct 08) for Vim 6.2
      --- 111-116 ---
      :source $VIMRUNTIME/delmenu.vim
      :set langmenu=de_DE.ISO_8859-1
      :source $VIMRUNTIME/menu.vim

      There is one drawback: All menus that you defined yourself will be gone.
      You
      will need to redefine them as well.
      +++ 111-116 +++
      :source $VIMRUNTIME/delmenu.vim
      :set langmenu=de_DE.ISO_8859-1
      :runtime! menu.vim

      If the menus you defined yourself are named "menu.vim" and reside in
      'runtimepath', they will also be re-sourced.
      ----- end -----

      Best regards,
      Tony.
    • Bram Moolenaar
      ... In many places this is indeed better. But not everywhere. ... OK. ... This would suggest Vim reads all menu.vim files, but it doesn t. Same remark for
      Message 2 of 3 , May 1 3:26 AM
      • 0 Attachment
        Antoine J. Mechelynck wrote:

        > Bug: Code examples given in help should in many cases go through all the
        > directories in 'runtimepath' rather than only $VIMRUNTIME.
        >
        > Fix: Replace (where needed) ":source $VIMRUNTIME/" by ":runtime! "

        In many places this is indeed better. But not everywhere.

        > ----- start -----
        > *** filetype.txt (2004 Jan 17) for Vim 6.2
        > --- 262 ---
        > :au BufRead *.html,<&faf;HTML> so $VIMRUNTIME/syntax/html.vim
        > +++ 262 +++
        > :au BufRead *.html,<&faf,HTML> runtime! syntax/html.vim

        OK.

        > *** gui.txt (2004 Apr 02) for Vim 6.2
        > --- 470 ---
        > :source $VIMRUNTIME/menu.vim
        > +++ 470 +++
        > :runtime! menu.vim

        This would suggest Vim reads all menu.vim files, but it doesn't.
        Same remark for other places where menu.vim is used.

        > *** lang.txt (2004 Feb 24) for Vim 6.2
        > --- 100-101 ---
        > have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", where "xx" is the
        > abbreviation of the language (mostly two letters).
        > +++ 100-102 +++
        > have to be placed in "<directory>/lang/xx/LC_MESSAGES", where "xx" is the
        > abbreviation of the language (mostly two letters) and <directory> is one of
        > the
        > directories in 'runtimepath'.

        As far as I know, only .mo files under $VIMRUNTIME actually work.

        > *** syntax.txt (2004 Mar 26) for Vim 6.2
        > --- 54-55 ---
        > What this command actually does is to execute the command >
        > :source $VIMRUNTIME/syntax/syntax.vim
        > +++ 54-55 +++
        > What this command actually does is to execute the command >
        > :runtime! syntax/syntax.vim

        Only the file in $VIMRUNTIME is used.

        > --- 131-137 ---
        > for example, the cpp.vim file could include the c.vim file: >
        > :so $VIMRUNTIME/syntax/c.vim
        >
        > The .vim files are normally loaded with an autocommand. For example: >
        > :au Syntax c source $VIMRUNTIME/syntax/c.vim
        > :au Syntax cpp source $VIMRUNTIME/syntax/cpp.vim
        > These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.
        > +++ 131-137 +++
        > for example, the cpp.vim file could include the c.vim file: >
        > :runtime! syntax/c.vim
        >
        > The .vim files are normally loaded with an autocommand. For example: >
        > :au Syntax c runtime! syntax/c.vim
        > :au Syntax cpp runtime! syntax/cpp.vim
        > These commands are normally in the file $VIMRUNTIME/syntax/synload.vim.

        OK.

        > --- 279 ---
        > +- Source $VIMRUNTIME/syntax/synload.vim from 'runtimepath'
        > +++ 279 +++
        > +- Source syntax/synload.vim from 'runtimepath'

        Only the file in $VIMRUNTIME is used.

        > *** usr_01.txt (2003 Jan 12) for Vim 6.2
        > --- 61-72 ---
        > setup, copy the example vimrc file. By doing this inside Vim you don't have
        > to check out where it is located. How to do this depends on the system you
        > are using:
        >
        > Unix: >
        > :!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc
        > MS-DOS, MS-Windows, OS/2: >
        > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/_vimrc
        > Amiga: >
        > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/.vimrc
        >
        > If the file already exists you probably want to keep it.
        > +++ 61-66 +++
        > setup, include the example vimrc file. An easy way to do this is to have the
        > line: >
        > runtime vimrc_example.vim
        >
        > near the start of your vimrc. Place your own preferences after that, so they
        > override the defaults, and not vice-versa.

        I prefer users to make a copy and modify it. It's an example, not
        something you would include and then overrule. That is too complicated
        for beginners.

        > *** usr_12.txt (2004 Jan 17) for Vim 6.2
        > --- 249 ---
        > :source $VIMRUNTIME/ftplugin/man.vim
        > +++ 249 +++
        > :runtime! ftplugin/man.vim

        OK.

        --
        hundred-and-one symptoms of being an internet addict:
        87. Everyone you know asks why your phone line is always busy ...and
        you tell them to send an e-mail.

        /// Bram Moolenaar -- Bram@... -- http://www.Moolenaar.net \\\
        /// Sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
        \\\ Project leader for A-A-P -- http://www.A-A-P.org ///
        \\\ Buy at Amazon and help AIDS victims -- http://ICCF.nl/click1.html ///
      • Antoine J. Mechelynck
        ... Of course you know Vim better than me. Trying to be complete, I ran the risk of excess. In my helpgrep, I skipped many instances where it looked obvious to
        Message 3 of 3 , May 1 5:38 AM
        • 0 Attachment
          Bram Moolenaar <Bram@...> wrote:
          > Antoine J. Mechelynck wrote:
          >
          > > Bug: Code examples given in help should in many cases go through
          > > all the directories in 'runtimepath' rather than only $VIMRUNTIME.
          > >
          > > Fix: Replace (where needed) ":source $VIMRUNTIME/" by ":runtime! "
          >
          > In many places this is indeed better. But not everywhere.

          Of course you know Vim better than me. Trying to be complete, I ran the risk
          of excess. In my helpgrep, I skipped many instances where it looked obvious
          to me that $VIMRUNTIME/ could stay. Apparently I didn't skip enough of them.

          [...]
          > > *** gui.txt (2004 Apr 02) for Vim 6.2
          > > --- 470 ---
          > > :source $VIMRUNTIME/menu.vim
          > > +++ 470 +++
          > > :runtime! menu.vim
          >
          > This would suggest Vim reads all menu.vim files, but it doesn't.
          > Same remark for other places where menu.vim is used.

          Didn't know that. Somehow I would have expected the opposite.

          [...]
          > > *** syntax.txt (2004 Mar 26) for Vim 6.2
          [...]
          > > --- 279 ---
          > > +- Source $VIMRUNTIME/syntax/synload.vim from 'runtimepath'
          > > +++ 279 +++
          > > +- Source syntax/synload.vim from 'runtimepath'
          >
          > Only the file in $VIMRUNTIME is used.

          Then I suppose the reference to 'runtimepath' should fall away. If it hadn't
          been there I wouldn't have suggested a change at this point.

          > > *** usr_01.txt (2003 Jan 12) for Vim 6.2
          > > --- 61-72 ---
          > > setup, copy the example vimrc file. By doing this inside Vim you
          > > don't have to check out where it is located. How to do this
          > > depends on the system you are using:
          > >
          > > Unix: >
          > > :!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc
          > > MS-DOS, MS-Windows, OS/2: >
          > > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/_vimrc
          > > Amiga: >
          > > :!copy $VIMRUNTIME/vimrc_example.vim $VIM/.vimrc
          > >
          > > If the file already exists you probably want to keep it.
          > > +++ 61-66 +++
          > > setup, include the example vimrc file. An easy way to do this is to
          > > have the line: >
          > > runtime vimrc_example.vim
          > >
          > > near the start of your vimrc. Place your own preferences after
          > > that, so they override the defaults, and not vice-versa.
          >
          > I prefer users to make a copy and modify it. It's an example, not
          > something you would include and then overrule. That is too
          > complicated
          > for beginners.

          Hm. I beg to differ. I know it will not be easy for me to sway your opinion
          in such a matter. Let me try though.

          In my approach (sourcing rather than copying) I see several advantages:

          (a) The newbie doesn't need to open a long and complex file, nor to try to
          understand it, in order to set his own preferences. Let's face it: the
          vimrc_example.vim is not something easy to understand, much less to modify
          sensibly, for someone who has just "taken the plunge" into Vim. (The first
          time I opened the _vimrc which [IIRC] the install process had created by
          copying the vimrc_example.vim, it gave me a headache. So, rather than modify
          something I didn't understand, I added one "source" command at the very
          bottom to source my own preferences -- the above process in reverse. Later I
          came to see that sourcing the original, unchanged vimrc_example.vim near the
          start of a user vimrc was both simpler and safer, just as easy for the
          newbie, and allowed placing a few specific commands like ":language messages
          en" before the code in the vimrc_example.vim if they appeared not to work
          after it.)

          (b) I'm not stuck with a "frozen" version of the vimrc_example.vim. Any bugs
          in it will be corrected by the next upgrade after they are found, with no
          user intervention (other than applying the upgrade of course) and with no
          corruption of any user's preferences.

          (c) It divides the responsibilities more neatly: Bram writes and maintains
          the vimrc_example.vim. I may accept, or not, any of its choices (as well as
          any of Vim's builtin defaults), but I do so by writing down my own choices
          at a different place (in my user vimrc). For anything I don't know or care
          about, I rely on Bram's choices, at least until I know better.

          Another possibility (possibly even better, but I hadn't thought of it before
          today) would be to copy the vimrc_example.vim to $VIM/vimrc (or source it
          from there) while placing user preferences in ~/.vimrc (or, on Windows, but
          in Vim parlance, in $HOME/_vimrc or $VIM/_vimrc). Thus the vimrc_example.vim
          would serve as "system default" (upon which, on a multi-user system, a
          competent sysadmin could build) while the user (newbie or otherwise) would
          start adding his own preferences to a "user" vimrc, which would start small
          and simple, and grow at the rhythm of the user's expertise.

          I think we both agree that the vimrc_example.vim is a good "general purpose"
          vimrc, a very good starting point for almost everyone: for most people it is
          "almost, but not quite" what they want. IMHO this implies that it makes
          sense to change a few of its settings, in an easily identifiable and
          reversible way.

          [...]
          > --
          > hundred-and-one symptoms of being an internet addict:
          > 87. Everyone you know asks why your phone line is always busy ...and
          > you tell them to send an e-mail.
          >
          > /// Bram Moolenaar -- Bram@... -- http://www.Moolenaar.net
          > \\\ /// Sponsor Vim, vote for features --
          > http://www.Vim.org/sponsor/ \\\ \\\ Project leader for
          > A-A-P -- http://www.A-A-P.org /// \\\ Buy at Amazon and help
          > AIDS victims -- http://ICCF.nl/click1.html ///

          Best regards,
          Tony
          mailto:antoine.mechelynck@...
          http://users.skynet.be/antoine.mechelynck/
        Your message has been successfully submitted and would be delivered to recipients shortly.