doc suggestion

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

doc suggestion

iler.ml
If vimscript functions had remark "Added in vim7.1.129", it would be useful.
For example, if you want to know how portable the script is.



--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Matt Wozniski-2

On Sat, Apr 4, 2009 at 3:17 PM, Yakov Lerner wrote:
>
> If vimscript functions had remark "Added in vim7.1.129", it would be useful.
> For example, if you want to know how portable the script is.

Probably not exactly what you're looking for, but I keep copies of vim
6.4.10 and 7.0.0 around just so that I can look at older runtimefiles
and docs and test scripts in older vims.

~Matt

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Ingo Karkat

On 04-Apr-09 22:21, Matt Wozniski wrote:
> On Sat, Apr 4, 2009 at 3:17 PM, Yakov Lerner wrote:
>> If vimscript functions had remark "Added in vim7.1.129", it would be useful.
>> For example, if you want to know how portable the script is.
>
> Probably not exactly what you're looking for, but I keep copies of vim
> 6.4.10 and 7.0.0 around just so that I can look at older runtimefiles
> and docs and test scripts in older vims.
>
> ~Matt

I keep old Vim versions (since 6.0), too, and grep the docs for the first
occurrence of a built-in function name. (But I also use these old Vims for
compatibility testing of my scripts.) I totally agree with Yakov that this would
be very helpful for script writers. I'd love to see these remarks below each
function's help text, with a formatting similar to those {not in Vi} and {not
available when compiled without the +whatever feature} remarks, e.g. {since 7.0}
or {optional third argument added with 7.1.42}.

Manually researching this for all built-in functions looks tedious, but maybe
someone can come up with a throwaway script that extracts the relevant info from
the patch info / CVS history / git / ...?

-- regards, ingo


--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Tony Mechelynck
In reply to this post by iler.ml

On 04/04/09 21:17, Yakov Lerner wrote:
> If vimscript functions had remark "Added in vim7.1.129", it would be useful.
> For example, if you want to know how portable the script is.

The docs are there, it just may be a little esoteric to find them.

        :helpgrep \<foobar(

or maybe, to narrow down the search,

        :vimgrep /\<foobar(/g $VIMRUNTIME/doc/version*.txt

will search, in the former case the text of all help files, or in the
latter case only that of the version*.txt helpfiles, for any mentioon of
the  foobar() function. If it was added to Vim not earlier than version
4.0, you'll find at exactly at which version and patchlevel that happened.

If you find out that it was introduced at version 6.3.87 you can test
for it by either

        if exists('*foobar')

or

        if version > 603 || (version == 603 && has('patch087'))

The latter is useful if, at some point after introducing the function,
an important bug in it (that you care about) was fixed.

If some version of Vim 3 already had the function (i.e. it was already
there as other than a "new feature" in Vim 4.0.000), then I suppose you
can say by now that it's been there "forever", and the only case when
you might still be unable to use it is if you use a non-feature-complete
Vim lacking some optional feature which includes that function. Of
course, -eval versions include no functions at all.


Best regards,
Tony.
--
The only really decent thing to do behind a person's back is pat it.

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

George V. Reilly

On Sat, Apr 4, 2009 at 5:31 PM, Tony Mechelynck
<[hidden email]> wrote:

> If some version of Vim 3 already had the function (i.e. it was already
> there as other than a "new feature" in Vim 4.0.000), then I suppose you
> can say by now that it's been there "forever", and the only case when
> you might still be unable to use it is if you use a non-feature-complete
> Vim lacking some optional feature which includes that function. Of
> course, -eval versions include no functions at all.

VimL scripting was introduced in Vim 5.0, eleven years ago, according
to http://en.wikipedia.org/wiki/Vim_(text_editor)#History. Personally,
I wouldn't expend more than a few minutes ensuring compatibility with
Vim 6.0 (2001), especially if you need dictionaries and other 7.0
features.

I think it's a mistake to continue supporting users who run really old
versions of Vim or really old operating systems. Their numbers are
dwindling and supporting them has real costs in terms of testing and
code complexity. Look at the horrendous amounts of conditional code in
the C source. If they don't want to upgrade (or can't), they'll have
to accept limitations. They certainly have to from other programs.
--
/George V. Reilly  [hidden email]
http://www.georgevreilly.com/blog  http://blogs.cozi.com/tech

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Tony Mechelynck

On 05/04/09 04:33, George V. Reilly wrote:

>
> On Sat, Apr 4, 2009 at 5:31 PM, Tony Mechelynck
> <[hidden email]>  wrote:
>
>> If some version of Vim 3 already had the function (i.e. it was already
>> there as other than a "new feature" in Vim 4.0.000), then I suppose you
>> can say by now that it's been there "forever", and the only case when
>> you might still be unable to use it is if you use a non-feature-complete
>> Vim lacking some optional feature which includes that function. Of
>> course, -eval versions include no functions at all.
>
> VimL scripting was introduced in Vim 5.0, eleven years ago, according
> to http://en.wikipedia.org/wiki/Vim_(text_editor)#History. Personally,
> I wouldn't expend more than a few minutes ensuring compatibility with
> Vim 6.0 (2001), especially if you need dictionaries and other 7.0
> features.

Didn't legacy Vi have exrc files? And how were they written if it wasn't
in what could be recognizably seen as what evolved to become vimscript?

>
> I think it's a mistake to continue supporting users who run really old
> versions of Vim or really old operating systems. Their numbers are
> dwindling and supporting them has real costs in terms of testing and
> code complexity. Look at the horrendous amounts of conditional code in
> the C source. If they don't want to upgrade (or can't), they'll have
> to accept limitations. They certainly have to from other programs.

Yeah, I rather think so too, but maybe with a different emphasis. I
think in terms of my present Vim 7.2 "with the latest patches", but I
write my vimrc etc. with appropriate "if has(...)" and "if exists(...)"
so they'll work on most Vim versions with as few errors as I can manage
(as they say, "be liberal in what you accept, conservative in what you
emit"). My whole vimrc includes if statements practically everywhere
(even ":if 1" in places) to avoid errors with the tiny minimum-features
version which I compile as a sanity check besides my day-to-day
workhorse Huge-with-GUI (whose binary is more than six times larger
after stripping).

When someone complains of a problem and mentions some "obsolete" Vim
version, I give as good an answer as I can think of, but I never fail to
mention the current version and patchlevel, with a sentence along the
lines of "I recommend that you upgrade: it will not necessarily cure
this problem, but it may cure other problems that you are or aren't
aware of".


Best regards,
Tony.
--
ARTHUR:       Now stand aside worthy adversary.
BLACK KNIGHT: (Glancing at his shoulder) 'Tis but a scratch.
ARTHUR:       A scratch?  Your arm's off.
                  "Monty Python and the Holy Grail" PYTHON (MONTY)
PICTURES LTD

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Bram Moolenaar
In reply to this post by iler.ml


Yakov Lerner wrote:

> If vimscript functions had remark "Added in vim7.1.129", it would be
> useful.  For example, if you want to know how portable the script is.

This gets really messy, especially if you also want to mention
extensions and changes done in a later version.  And worse when
including bug fixes.

You can find the information in the version*.txt help files.
E.g. with ":help version7" you can see that all the List and Dictionary
stuff has been added in Vim 7.0.  So instead of adding a remark "since
Vim 7.0" to every command, function, variable, etc. that uses a List
there is only this remark.  It's a bit more work to figure out when
something got added, but it avoids a lot of mess scattered in the help
files.  Some people may already find the {not in Vi} comments annoying.

--
TALL KNIGHT OF NI: Ni!
                 "Monty Python and the Holy Grail" PYTHON (MONTY) PICTURES LTD

 /// Bram Moolenaar -- [hidden email] -- 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://ICCF-Holland.org    ///

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Tony Mechelynck

On 05/04/09 17:54, Bram Moolenaar wrote:
> [...] Some people may already find the {not in Vi} comments annoying.

Well, OT1H they are somewhat annoying, but OTOH they are a warning that
there might (not necessarily, but possibly) be a behaviour difference
depending on the 'compatible' status; and seeing how many newbies are
still constantly bitten by the 'compatible' worm ('t ain't a bug, haha
;-) ), I'd say that on the whole those comments are useful, even for
people who never use "legacy" Vi.


Best regards,
Tony.
--
Absinthe makes the tart grow fonder.

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Spencer Collyer
In reply to this post by Tony Mechelynck

On Sun, 05 Apr 2009 11:38:18 +0200, Tony Mechelynck wrote:
>
> On 05/04/09 04:33, George V. Reilly wrote:
> >
> > On Sat, Apr 4, 2009 at 5:31 PM, Tony Mechelynck
> > <[hidden email]>  wrote:
> >

> > VimL scripting was introduced in Vim 5.0, eleven years ago,
> > according to
> > http://en.wikipedia.org/wiki/Vim_(text_editor)#History. Personally,
> > I wouldn't expend more than a few minutes ensuring compatibility
> > with Vim 6.0 (2001), especially if you need dictionaries and other
> > 7.0 features.
>
> Didn't legacy Vi have exrc files? And how were they written if it
> wasn't in what could be recognizably seen as what evolved to become
> vimscript?
>

IIRC, Vi's exrc files were just lists of Ex commands.

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

George V. Reilly

On Sun, Apr 5, 2009 at 11:12 PM, Spencer Collyer
<[hidden email]> wrote:

>
> On Sun, 05 Apr 2009 11:38:18 +0200, Tony Mechelynck wrote:
>>
>> On 05/04/09 04:33, George V. Reilly wrote:
>> >
>> > On Sat, Apr 4, 2009 at 5:31 PM, Tony Mechelynck
>> > <[hidden email]>  wrote:
>> >
>
>> > VimL scripting was introduced in Vim 5.0, eleven years ago,
>> > according to
>> > http://en.wikipedia.org/wiki/Vim_(text_editor)#History. Personally,
>> > I wouldn't expend more than a few minutes ensuring compatibility
>> > with Vim 6.0 (2001), especially if you need dictionaries and other
>> > 7.0 features.
>>
>> Didn't legacy Vi have exrc files? And how were they written if it
>> wasn't in what could be recognizably seen as what evolved to become
>> vimscript?
>>
>
> IIRC, Vi's exrc files were just lists of Ex commands.

Pretty much just :map and :set. Look at the code in $VIMRUNTIME/macros
and shudder.
--
/George V. Reilly  [hidden email]
http://www.georgevreilly.com/blog  http://blogs.cozi.com/tech

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---

Reply | Threaded
Open this post in threaded view
|

Re: doc suggestion

Tony Mechelynck

On 06/04/09 09:09, George V. Reilly wrote:
> On Sun, Apr 5, 2009 at 11:12 PM, Spencer Collyer
> <[hidden email]>  wrote:
[...]
>> IIRC, Vi's exrc files were just lists of Ex commands.
>
> Pretty much just :map and :set. Look at the code in $VIMRUNTIME/macros
> and shudder.

:-) Depends what in $VIMRUNTIME/macros. matchit.vim is a real work of
art, except of course that it rightly belongs in $VIMRUNTIME/plugin.


Best regards,
Tony.
--
This fortune intentionally not included.

--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_dev" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---