preliminary rubycomplete documentation for review

On 4/20/06, Mark Guzman <segfaulthasno.info> wrote:
> Everyone,
>   Please take a moment and look over ft-ruby-omni in
the attached file.
>   --mark


My suggested replacement for the relevant section is below. 
I aimed
for a style that's consistent with the rest of the Vim
online help.

It should be viewed in Vim with ':set filetype=help' to
see the highlighting.

BTW Mark, your prelim documentation mentioned that object
specific
completion would be done after any of {. : ::}.  What is
":" supposed
to do?

Cheers,
Gavin

P.S. Please only send the relevant text in future.  The
attachment
before was so large that Mailman asked me to approve it
before it
could be posted to the list!


== begin

RUBY                                                   
*ft-ruby-omni*

Completion of Ruby code requires that vim be built with
|+ruby|.

Ruby completion will parse your buffer on demand in order to
provide a list of
completions.  These completions will be drawn from modules
loaded by 'require'
and modules defined in the current buffer.

The completions provided by CTRL-X CTRL-O are sensitive to
the context:

          CONTEXT                          COMPLETIONS
PROVIDED ~

 1. Not inside a class definition    Classes, constants and
globals

 2. Inside a class definition        Methods or constants
defined in the class

 3. After '.' or '::'                Methods applicable
to the object being
                                       dereferenced

Notes:
 - Vim will load/evaluate code in order to provide
completions.  This may
   cause some code execution, which may be a concern.
 - In context 2 above, anonymous classes are not supported.
 - In context 3 above, Vim will attempt to determine the
methods supported by
   the object.

== end

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

Gavin Sinclair wrote:
>
>
> My suggested replacement for the relevant section is
below.  I aimed
> for a style that's consistent with the rest of the Vim
online help.
>
> It should be viewed in Vim with ':set filetype=help'
to see the highlighting.
>
> BTW Mark, your prelim documentation mentioned that
object specific
> completion would be done after any of {. : ::}.  What
is ":" supposed
> to do?
>
> Cheers,
> Gavin
>
> P.S. Please only send the relevant text in future.  The
attachment
> before was so large that Mailman asked me to approve it
before it
> could be posted to the list!
>   
Gavin,
: will complete symbols. If done with no preceding text it
will provide
a list of global symbols.
Sorry about the file-size, I'll snip the segment next time.

Here's a slightly updated version of the doc:

== begin

RUBY                                                   
*ft-ruby-omni*

Completion of Ruby code requires that vim be built with
|+ruby|.

Ruby completion will parse your buffer on demand in order to
provide a list of
completions.  These completions will be drawn from modules
loaded by 'require'
and modules defined in the current buffer.

The completions provided by CTRL-X CTRL-O are sensitive to
the context:

          CONTEXT                          COMPLETIONS
PROVIDED ~

 1. Not inside a class definition    Classes, constants and
globals

 2. Inside a class definition        Methods or constants
defined in the class

 3. After '.', '::' or ':'           Methods
applicable to the object being
                                       dereferenced, Symbols
in the case of ':'

Notes:
 - Vim will load/evaluate code in order to provide
completions.  This may
   cause some code execution, which may be a concern.
 - In context 2 above, anonymous classes are not supported.
 - In context 3 above, Vim will attempt to determine the
methods supported by
   the object.
 - Vim can detect and load the Rails environment for files
within a rails 
   project. The feature is disabled by default, to enable it
add
   let g:rubycomplete_rails = 1
   to your vimrc

== end


-- 
sic transit gloria et adulescentia 
blog | http://blog.hasno.info/bl
og
wiki | http://wiki.hasno.info

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On 4/20/06, Mark Guzman <segfaulthasno.info> wrote:

> Gavin,
> : will complete symbols. If done with no preceding text
it will provide
> a list of global symbols.

[...]

>
>  3. After '.' or '::'                 Methods
applicable to the object being
>                                        dereferenced

 4. After ':' or ':foo'                    Symbol name
(beginning with 'foo')

How does that sound?  Completing symbols is completely
different to
completing methods, so it's confusing to read them lumped
together.

Completing symbols seems like a pointless feature.  When I
want to
complete a symbol, Vim's normal text completion (CTRL-P in
insert
mode) does the job just fine.  I hate to think of the
processing
involved in getting all the symbol names and narrowing it
  Not
that
I've tried it, though.

Gavin

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On Thu, Apr 20, 2006 at 06:44:25PM +1000, Gavin Sinclair
wrote:
> On 4/20/06, Mark Guzman <segfaulthasno.info> wrote:
> 
> > Gavin,
> > : will complete symbols. If done with no preceding
text it will provide
> > a list of global symbols.
> 
> [...]
> 
> >
> >  3. After '.' or '::'                 Methods
applicable to the object being
> >                                       
dereferenced
> 
>  4. After ':' or ':foo'                    Symbol
name (beginning with 'foo')
> 
> How does that sound?  Completing symbols is completely
different to
> completing methods, so it's confusing to read them
lumped together.

Sounds good to me. I've added it to doc/ft-ruby-omni.txt
 
> Completing symbols seems like a pointless feature. 
When I want to
> complete a symbol, Vim's normal text completion
(CTRL-P in insert
> mode) does the job just fine.  I hate to think of the
processing
> involved in getting all the symbol names and narrowing
it  
Not that
> I've tried it, though.

Am I right in assuming this will be useful for rails users,
in
particular?

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On 4/20/06, Doug Kearns <dougkearnsgmail.com> wrote:
> >  4. After ':' or ':foo'                   
Symbol name (beginning with 'foo')
> >
> > How does that sound?  Completing symbols is
completely different to
> > completing methods, so it's confusing to read
them lumped together.
>
> Sounds good to me. I've added it to
doc/ft-ruby-omni.txt

So this is user documentation, not to be inserted into
insert.txt like
Mark distributed to us?  It's the user's responsibility to
generate it
after installation?

> > Completing symbols seems like a pointless feature.
 When I want to
> > complete a symbol, Vim's normal text completion
(CTRL-P in insert
> > mode) does the job just fine.  I hate to think of
the processing
> > involved in getting all the symbol names and
narrowing it   Not that
> > I've tried it, though.
>
> Am I right in assuming this will be useful for rails
users, in
> particular?

Rails uses a lot of symbols, to be sure, but once you've
typed it once
anywhere in any buffer, symbol completion is only a CTRL-P
away 

Gavin

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On Thu, Apr 20, 2006 at 11:19:25PM +1000, Gavin Sinclair
wrote:
> On 4/20/06, Doug Kearns <dougkearnsgmail.com> wrote:
> > >  4. After ':' or ':foo'                  
 Symbol name (beginning with 'foo')
> > >
> > > How does that sound?  Completing symbols is
completely different to
> > > completing methods, so it's confusing to
read them lumped together.
> >
> > Sounds good to me. I've added it to
doc/ft-ruby-omni.txt
> 
> So this is user documentation, not to be inserted into
insert.txt like
> Mark distributed to us?  It's the user's
responsibility to generate it
> after installation?

Well it's possibly both now. I used to have the syntax
documentation in
syntax/doc/ruby.txt but since we're also adding some for
omni completion
I thought it might be a good idea to make them more
obviously accessible
to the user. I've sent the contents of ft-ruby-omni.txt to
Bram and he's
already added it to insert.txt.

If you think it's confusing there's no need to package up
the doc
directory for release. It just seems like a good idea to
have it in the
repository too - for when we're all long gone...bus or no
bus. 
 
> > > Completing symbols seems like a pointless
feature.  When I want to
> > > complete a symbol, Vim's normal text
completion (CTRL-P in insert
> > > mode) does the job just fine.  I hate to
think of the processing
> > > involved in getting all the symbol names and
narrowing it   Not that
> > > I've tried it, though.
> >
> > Am I right in assuming this will be useful for
rails users, in
> > particular?
> 
> Rails uses a lot of symbols, to be sure, but once
you've typed it once
> anywhere in any buffer, symbol completion is only a
CTRL-P away 

Sure but how many times are you going to call something like
url_for in
a simple controller and with the same 'options'? I assume,
from what
Mark was saying, he has some way to provide the appropriate
symbols.
 
Note: I've only ever looked at Rails once and this was the
first method
I could find in my old rails 'sandbox'. 

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On Fri, Apr 21, 2006 at 12:42:26AM +1000, Doug Kearns wrote:
> On Thu, Apr 20, 2006 at 11:19:25PM +1000, Gavin
Sinclair wrote:
> > On 4/20/06, Doug Kearns <dougkearnsgmail.com> wrote:
> > > >  4. After ':' or ':foo'             
      Symbol name (beginning with 'foo')
> > > >
> > > > How does that sound?  Completing symbols
is completely different to
> > > > completing methods, so it's confusing
to read them lumped together.
> > >
> > > Sounds good to me. I've added it to
doc/ft-ruby-omni.txt
> > 
> > So this is user documentation, not to be inserted
into insert.txt like
> > Mark distributed to us?  It's the user's
responsibility to generate it
> > after installation?
> 
> Well it's possibly both now. I used to have the syntax
documentation in
> syntax/doc/ruby.txt but since we're also adding some
for omni completion
> I thought it might be a good idea to make them more
obviously accessible
> to the user. I've sent the contents of
ft-ruby-omni.txt to Bram and he's
> already added it to insert.txt.

If it was distributed I hadn't actually considered
_installing_ it
locally. I doubt it'd change enough to make that worthwhile
although
Mark seems to have some plans for the omni completion so
maybe it would
be?
 
<snip>

Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On 4/21/06, Doug Kearns <dougkearnsgmail.com> wrote:
> >
> > So this is user documentation, not to be inserted
into insert.txt like
> > Mark distributed to us?  It's the user's
responsibility to generate it
> > after installation?
>
> Well it's possibly both now. I used to have the syntax
documentation in
> syntax/doc/ruby.txt but since we're also adding some
for omni completion
> I thought it might be a good idea to make them more
obviously accessible
> to the user. I've sent the contents of
ft-ruby-omni.txt to Bram and he's
> already added it to insert.txt.

As per my ranting in the other email: I agree, the
accessability is a
good thing, outweighing other concerns.

Is it too late to get a website link in there?

> If you think it's confusing there's no need to
package up the doc
> directory for release. It just seems like a good idea
to have it in the
> repository too - for when we're all long gone...bus or
no bus. 

Agree to that too.  The FAQ or something should explain the
situation.

> > Rails uses a lot of symbols, to be sure, but once
you've typed it once
> > anywhere in any buffer, symbol completion is only
a CTRL-P away 
>
> Sure but how many times are you going to call something
like url_for in
> a simple controller and with the same 'options'?

Lots of times 

Gavin

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On 4/21/06, Doug Kearns <dougkearnsgmail.com> wrote:
> > >
> > > So this is user documentation, not to be
inserted into insert.txt like
> > > Mark distributed to us?  It's the user's
responsibility to generate it
> > > after installation?
> >
> > Well it's possibly both now. I used to have the
syntax documentation in
> > syntax/doc/ruby.txt but since we're also adding
some for omni completion
> > I thought it might be a good idea to make them
more obviously accessible
> > to the user. I've sent the contents of
ft-ruby-omni.txt to Bram and he's
> > already added it to insert.txt.
>
> If it was distributed I hadn't actually considered
_installing_ it
> locally. I doubt it'd change enough to make that
worthwhile although
> Mark seems to have some plans for the omni completion
so maybe it would
> be?

'Fraid I don't have a quick or a good answer to that one. 
There are
obvious advantages in having the docs embedded in Vim's
docs.

Perhaps if the ft-ruby-omni docs included a link to the
website people
would know where to look for updates and updated
information.

Also, if it's embedded, people should know that compiling
with +ruby
is a necessary but not sufficient condition for omni
completion: it
must be enabled in the .vimrc or (better) an ftplugin file. 
Another
reason to link to vim-ruby.rubyforge.org.

I must confess I hadn't realised that the Ruby *syntax*
docs were
embedded.  Since they are, let's ensure the omni ones are
too.

And what about a website link in the syntax docs, Doug?

Cheers,
Gavin

_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel

On Fri, Apr 21, 2006 at 08:35:34AM +1000, Gavin Sinclair
wrote:

<snip>
 
> Perhaps if the ft-ruby-omni docs included a link to the
website people
> would know where to look for updates and updated
information.

Well they should know to look in the runtime file header.
That's why
it's there - same as any other runtime file.
 
> Also, if it's embedded, people should know that
compiling with +ruby
> is a necessary but not sufficient condition for omni
completion: it
> must be enabled in the .vimrc or (better) an ftplugin
file.  Another
> reason to link to vim-ruby.rubyforge.org.

This is no different from all the other omni scripts - they
all have the
same requirements which are documented in the Vim help.
 
> I must confess I hadn't realised that the Ruby
*syntax* docs were
> embedded.  Since they are, let's ensure the omni ones
are too.

Hmmm, must be because the defaults are so spectacularly
good.
 
> And what about a website link in the syntax docs, Doug?

Well if we're going to go down this path perhaps we could
also consider
creating a file like:

:help sql.txt
 
Regards,
Doug
_______________________________________________
vim-ruby-devel mailing list
vim-ruby-develrubyforge.org

http://rubyforge.org/mailman/listinfo/vim-ruby-devel