Update of netbeans help file

[Philippe Fremy]

Hi,

The current netbeans help file contains outdated information. It
describes the installation and configuration of the External Editor
plugin for NetBeans, but this plugin no longer exists.

Here is my proposition for an updated netbeans help file with several
enhancements. The enhancements are based on the questions popping
regularly on this list and on the difficulties I had during the
implementation of the protocol.

Changes are:
- it gives a bit more historical background.

- it is not focused only on the NetBeans External Editor plugin, it
references several projects taking advantage of the Vim netbeans interface.

- it describes in generic terms what you can do with the netbeans
interface, and insists that this carry no java or NetBeans dependency.

- it explains how to configure Vim to get logging information from the
netbeans inteface. Very useful when working on an implementation.

- all the description of the protocol messages has been kept asis, with
small additions in places where I found ambiguities during my
implementation.

- better description of the concept of hotkeys

- rework a bit the order in which things are presented.

There are probably some frenchism in my english, so do not hesitate to
pinpoint strange-sounding sentences for english speakers.

I'll be happy to improve the file with your feedback.

cheers,

Philippe

[Ilya Bobir]

Philippe Fremy wrote:
> [...]
> For sending key strokes to Vim or for evaluating functions in Vim, you must
> use the|clientserver|interface.
>

use the |clientserver| interface.

> [...]
> kind first item example ~
> Command bufID:name!seqno 11:showBalloon!123 "text"
> Function bufID:name/seqno 11:getLength/123
> Reply seqno 123 5000
> Event bufID:name=123 11:keyCommand=123 "S-F2"
>

Event bufID:name=seqno 11:keyCommand=123 "S-F2"

> [...]
>
> newDotAndMark off off
>

Remove extra "off"?

> [...]
>
> version vers Report the version of the interface implementation. Vim
> reports "2.2" (including the quotes).
>

Is it "2.4" now?

[Philippe Fremy]

Ilya Bobir wrote:

> Philippe Fremy wrote:
>> [...]
>> For sending key strokes to Vim or for evaluating functions in Vim, you must
>> use the|clientserver|interface.
>>
>
> use the |clientserver| interface.

When shown in the help file, the | is not visible, so it looks normal.

>> [...]
>> kind first item example ~
>> Command bufID:name!seqno 11:showBalloon!123 "text"
>> Function bufID:name/seqno 11:getLength/123
>> Reply seqno 123 5000
>> Event bufID:name=123 11:keyCommand=123 "S-F2"
>>
>
> Event bufID:name=seqno 11:keyCommand=123 "S-F2"

Fixed.

>> newDotAndMark off off
>>

Actually, this is not syntax error. This is what the code does:

sprintf(buf, "%d:newDotAndMark=%d %ld %ld\n", bufno, r_cmdno, off, off);

Now why is the offset output twice ? That's probably part of history...

>
> Remove extra "off"?
>
>> [...]
>>
>> version vers Report the version of the interface implementation. Vim
>> reports "2.2" (including the quotes).
>>
>
> Is it "2.4" now?

Indeed. Explanations about the versions is not very good at the moment.
I'll see if I can explain something more meaningful.

For the old-timers here, do you remember what where the events leading
to version upgrades of netbeans ?

cheers,

Philippe

[Markus Heidelberg]

Philippe Fremy, 21.05.2008:

> Ilya Bobir wrote:
> > Philippe Fremy wrote:
> >> [...]
> >> For sending key strokes to Vim or for evaluating functions in Vim, you
> >> must use the|clientserver|interface.
> >
> > use the |clientserver| interface.
>
> When shown in the help file, the | is not visible, so it looks normal.

Compared to other parts of the Vim help, there is always a leading/trailing
space before/after the |. Execption seems to be at punctuation marks.

Markus

[Ilya Bobir]

Philippe Fremy wrote:
> Ilya Bobir wrote:
>
>
>> Philippe Fremy wrote:
>>
>>> [...]
>>> For sending key strokes to Vim or for evaluating functions in Vim, you must
>>> use the|clientserver|interface.
>>>
>>>
>> use the |clientserver| interface.
>>
>
> When shown in the help file, the | is not visible, so it looks normal.
>

That was exactly my first thought, but then I looked through the file
looking for other keywords. It appears that all of them use extra
spaces around a keyword.

[Philippe Fremy]

Here is an updated version, with the fixes included (spaces around
clientserver, small typos).

Philippe

[Dominique Pelle]

On Fri, May 23, 2008 at 11:42 AM, Philippe Fremy <ph...@freehackers.org> wrote:

> 1. Introduction *netbeans-intro*

> The Netbeans interface was initially developed to integrate Vim into the
> NetBeans java IDE, using the external editor plugin. This NetBeans plugin no longer

A bit nitpicking: the document sometimes uses the terms "Netbeans",
"NetBeans" or "netbeans" (different cases). For consistency, I think it's
better to use "NetBeans" since this is what the old documentation
used.

Similarly, java should be Java, python should be Python, and vim should
be Vim I think (as in other help files of Vim).

> There are existing implementation

There are existing implementations

> Check the specific projets page to see how to use Vim with these projects.

Check the specific project pages to see [...]

> be notified when buffer are open or closed

be notified when buffers are opened or closed

> setReadOnly
> Set a file as readonly
> Implemented in verion 2.3.

typo: verion -> version

> When running Vim, set the following environement variables:

typo: environement -> environment

Thanks!
-- Dominique

[Philippe Fremy]

Dominique Pelle wrote:
> On Fri, May 23, 2008 at 11:42 AM, Philippe Fremy <ph...@freehackers.org> wrote:
>
>> 1. Introduction *netbeans-intro*
>
>> The Netbeans interface was initially developed to integrate Vim into the
>> NetBeans java IDE, using the external editor plugin. This NetBeans plugin no longer
>
> A bit nitpicking: the document sometimes uses the terms "Netbeans",
> "NetBeans" or "netbeans" (different cases). For consistency, I think it's
> better to use "NetBeans" since this is what the old documentation
> used.

Indeed, that's a mistake.

It reflects the fact that I am very uncomfortable naming a socket
protocol that belongs to Vim with the trademarked name of an external
product (that no longer supports Vim integration).

> [few typos]

Ok, all described typos and inconsistencies have been fixed. Not all of
them were coming from me :-)

Thanks for taking the time to review the file.

Philippe

[Adri Verhoef]

On Mon, May 26, 2008 at 15:05:40 +0000, Philippe Fremy wrote:
> 4. Error Messages *netbeans-messages*
>
> Those error messages are specific to NetBeans socket protocol:
^^^^^
These?

> Read-only file
[]
> So Vim does not allow modifications to files when run with
> in NetBeans mode.

run within?

> 6. NetBeans protocol *netbeans-protocol*
[]
> see http://www.a-a-p.org) and other IDE. The extensions are marked with

the other IDE? another IDE? other IDEs?

> NetBeans users (ie, not Agide users). However, a bug was fixed which could

i.e.?

> seqno The IDE uses a sequence number for Commands and Functions. A
> Reply must use the sequence number of the Function that it is
> associated with.

with which it is associated.?

Adri

[Philippe Fremy]

Thanks for the correction.

Here is the updated version of the netbeans help file.

Philippe