Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Confusing syntax in README #281

Closed
dideler opened this issue Mar 9, 2013 · 9 comments · Fixed by #496
Closed

Confusing syntax in README #281

dideler opened this issue Mar 9, 2013 · 9 comments · Fixed by #496
Labels

Comments

@dideler
Copy link

dideler commented Mar 9, 2013

A few of the commands in the README contain confusing syntax. I'm not familiar with (!), what does it mean? For example, if I want to update my bundles, it's unclear if I should run :BundleInstall or :BundleInstall(!) -- I assume it's the former because I don't believe the latter is a valid command. Still, it's confusing.

" :BundleInstall(!)    - install(update) bundles
" :BundleSearch(!) foo - search(or refresh cache first) for foo
" :BundleClean(!)      - confirm(or auto-approve) removal of unused bundles
@deiga
Copy link

deiga commented Mar 9, 2013

Thats trying to say that :BundleInstall installs bundles and :BundleInstall! updates bundles.
But I agree that the syntax is a bit confusing

@dideler
Copy link
Author

dideler commented Mar 9, 2013

Ah, that seems obvious now, but hindsight is 20/20.

Putting them on separate lines would be the least confusing but also takes up most space, e.g.

:BundleInstall - install bundles
:BundleInstall! - update bundles

Or on the same line but separated, e.g.

:BundleInstall - install bundles, or update bundles with :BundleInstall!

Or hinting at alternative behaviour, e.g.

:BundleInstall - Installs bundles. Append '!' to update bundles. 

And so forth for all commands that have a secondary option.

@lucc
Copy link
Contributor

lucc commented Apr 24, 2014

If the information has to stay on one line (@gmarik once noted he likes the example vimrc to be short) I vote for square brackets because that's what the vim help and man pages use for optional stuff.

@jdevera
Copy link
Contributor

jdevera commented Apr 28, 2014

It's only confusing if the user does not know Vim commands at all. It is a well known thing that many Vim commands use the exclamation mark at the end to modify their behaviour, normally the more destructive option of the command.

So yes, we can split the lines, although most would have repeated text, but come on.

@dideler
Copy link
Author

dideler commented Apr 28, 2014

It's only confusing if the user does not know Vim commands at all.

That's a bit of a hyperbole. At the time I opened this issue, I've happily been using Vim for a while without ever having come across the bang (!) syntax. I'm sure there are many more who fall into the same boat.

@hackhowtofaq
Copy link

+1

I am using Vim/Ruby for more than 5 years and still I didn't get it with a first read! So, I agree with dideler, the documentation should clearly indicate what is going on.

@gmarik
Copy link
Contributor

gmarik commented Jul 12, 2014

So what's your version on how documentation should look like?

@hackhowtofaq
Copy link

I am happy with separate lines

:BundleInstall - install bundles
:BundleInstall! - update bundles

thanx

@jdevera
Copy link
Contributor

jdevera commented Jul 15, 2014

Ok, let's have a PR, then. I'll merge it.

gmarik added a commit that referenced this issue Jul 17, 2014
@gmarik gmarik mentioned this issue Jul 17, 2014
gmarik added a commit that referenced this issue Jul 18, 2014
shippy pushed a commit to shippy/Vundle.vim that referenced this issue Apr 12, 2017
shippy pushed a commit to shippy/Vundle.vim that referenced this issue Jun 2, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants