Permalink
Browse files

improve docs:

- make it easier to understand that for gentoo users there aretwo ways to install VAM
- split docs into a getting-started.txt file and an "additional-docs" file
because new users judge the complexity of a script by the length of documentation.
(This happened twice on #irc). But VAM is very easy to use once you get it.
- make it easier to understand what the minimal setup is and that it is an alternative
to the SetupVAM function
- move the EnsureVAMIsOnDisk code into its own function and call it that way
I hope this makes it easier to focus on the important lines
  • Loading branch information...
1 parent 35e9f66 commit ca3b3c9926fd1b6f1810bd8e8e2239e3b13dcdb7 @MarcWeber committed Apr 4, 2012
@@ -1,14 +1,8 @@
-*vim-addon-manager.txt* Declarative package manager for Vim
+*vim-addon-manager-additional-documentation.txt* Declarative package manager for Vim
==============================================================================
CONTENTS *VAM-contents*
+ 1., 2. see vim-addon-manager-getting-started.txt
- 0. GETTING STARTED & LOOKING FOR HELP <<
-
- 1. Intro |VAM-intro|
- 2 Installation & installing plugins |VAM-installation|
- 2.2 Names of addons and addon soucres |VAM-addon-names|
- 2.3 Example: configurable setup |VAM-complex-setup-sample|
- 2.4 unattended installation |VAM-unattended-installation|
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
@@ -25,321 +19,6 @@ CONTENTS *VAM-contents*
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
-==============================================================================
-
-0. GETTING STARTED & LOOKING FOR HELP - something doesn't work
-
-Getting started fast: ~
-Read: |VAM-installation| and |VAM-addon-names|
-
-
-NEED HELP: ~
-Join irc.freenode.net, /join #vim. Ask there. VAM has many users
-MarcWeber is hanging around often so ping him or create a github ticket [1] and
-people will try to help you. You should skim the docs before asking for
-help though. Also see |VAM-author|
-[1] https://github.com/MarcWeber/vim-addon-manager/issues
-
-WHY VAM?: ~
- - two maintainers (ZyX and Marc Weber)
- - friendly to users (install addons by name)
- - propagates collaborative coding by providing simple dependeoncy managament
- improving code sharing
- - supports many sources (git,hg,bzr,svn,www.vim.org)
- - provides a way to deprecate plugins which are superseded by others
- - most plugins can also be loaded at runtime (some problems may [BUG 10])
- - some Windows support
- - is not too shy telling you that alternatives exist (and which one)
- - copes with "subdirectories contain vim runtimepath" cases
-
-==============================================================================
-1. Intro *VAM-intro*
-
-VAM is a shortcut for vim-addon-manager.
-Difference addon/plugin: None.
->
- :h plugin
-tells you about the old manual manual way of installing plugins. VAM helps
-keeping ~/.vim clean by separating plugins from each other.
-
-Features:
-
- - Separate directories for each plugins
- - Dependency resolution
- - Popular VCS support: plugin supports fetching from Git, Mercurial,
- Subversion and Bazaar repositories
-
-Dependencies:
- - Curl, wget or other program that can output URL contents to stdout (in
- order to get http protocol support)
- - Git, Mercurial, Subversion and Bazaar (if you want to install plugins
- from appropriate repositories)
- - Either tar, gzip and zip or 7-zip (required for unpacking some addons)
-
-What does "Declarative package manager" mean? The final behaviour of Vim
-should be declared once. Your ~/.vimrc and |:UpdateAddons| should be enough
-to cause same Vim behaviour everywhere.
-
-
-==============================================================================
-2. Installation *VAM-installation*
-
-Windows users: see |VAM-windows|.
-Gentoo users: see |VAM-gentoo|.
-linux/cygwin/OSX (anything support /bin/sh like shells) users:
-
-The recommended setup is shown below. It installs VAM if it is not on your disk
-using a short shell script.
-
-Then it adds its PATH to Vim's |runtimepath|. If you don't like vam_install_path
-default setting change it.
-
-You make VAM install plugins by adding their names to the list in
- |vam#ActivateAddons()|. Try understanding the comments. They'll help you get
-started fast.
-
-recommended setup ~
-Add the following to your .vimrc >
-
- fun! SetupVAM()
- " set advanced options like this:
- " let g:vim_addon_manager = {}
- " let g:vim_addon_manager['key'] = value
-
- " YES, you can customize this vam_install_path path and everything
- " still works!
- let vam_install_path = expand('$HOME') . '/.vim/vim-addons'
- exec 'set runtimepath+='.vam_install_path.'/vim-addon-manager'
-
- " * unix based os users may want to use this code checking out VAM
- " * windows users want to use http://mawercer.de/~marc/vam/index.php
- " to fetch VAM, VAM-known-repositories and the listed plugins
- " without having to install curl, unzip, git tool chain first
- " -> BUG [4] (git-less installation)
- if !filereadable(vam_install_path.'/vim-addon-manager/.git/config')
- \&& 1 == confirm("Clone VAM into ".vam_install_path."?","&Y\n&N")
- " I'm sorry having to add this reminder. Eventually it'll pay off.
- call confirm("Remind yourself that most plugins ship with ".
- \"documentation (README*, doc/*.txt). It is your ".
- \"first source of knowledge. If you can't find ".
- \"the info you're looking for in reasonable ".
- \"time ask maintainers to improve documentation")
- call mkdir(vam_install_path, 'p')
- execute '!git clone --depth=1 git://github.com/MarcWeber/vim-addon-manager '.shellescape(vam_install_path, 1).'/vim-addon-manager'
- " VAM runs helptags automatically when you install or update
- " plugins
- exec 'helptags '.fnameescape(vam_install_path.'/vim-addon-manager/doc')
- endif
-
- " Example: drop git sources unless git is in PATH. Same plugins can
- " be installed form www.vim.org. Lookup MergeSources to get more control
- " let g:vim_addon_manager['drop_git_sources'] = !executable('git')
-
- call vam#ActivateAddons([], {'auto_install' : 0})
- " sample: call vam#ActivateAddons(['pluginA','pluginB', ...], {'auto_install' : 0})
- " - look up source from pool (<c-x><c-p> complete plugin names):
- " ActivateAddons(["foo", ..
- " - name rewritings:
- " ..ActivateAddons(["github:foo", .. => github://foo/vim-addon-foo
- " ..ActivateAddons(["github:user/repo", .. => github://user/repo
- " Also see section "2.2. names of addons and addon sources" in VAM's documentation
- endfun
- call SetupVAM()
- " experimental [E1]: load plugins lazily depending on filetype, See
- " NOTES
- " experimental [E2]: run after gui has been started (gvim) [3]
- " option1: au VimEnter * call SetupVAM()
- " option2: au GUIEnter * call SetupVAM()
- " See BUGS sections below [*]
- " Vim 7.0 users see BUGS section [3]
-
-
-minimal setup ~
- This is the minimal setup which makes VAM work.
- If you remove all comments in the large "recommend setup" above and drop the
- code checking out VAM automatically this is which is left:
->
- set rtp+=PATH-TO-VAM
- call vam#ActivateAddons([], {'auto_install' : 0})
-
-
-NOTES: ~
- experimental: load plugins lazily depending on filetype [E1]~
->
- let ft_addons = {
- \ '^\%(c\|cpp\)$': [ 'plugin-for-c-development' ],
- \ 'javascript': [ 'plugin-for-javascript' ]
- \ }
- au FileType * for l in values(filter(copy(ft_addons), string(expand('<amatch>')).' =~ v:key')) | call vam#ActivateAddons(l, {'force_loading_plugins_now':1}) | endfor
-< Provide feedback about this. If it works we may add it as builtin
-
- experimental: setup VAM when GUI has started [E2] ~
- Depending on the option you choose to run ActivateAddons Vim may not be
- able to show the questions correctly asking you to install a plugin.
- If that's the case (for whatever reason) I recommend installing the plugin
- using |:InstallAddons| or |:ActivateAddons| before adding it to the list in
- .vimrc
-
- If you're annoyed by the message: >
- "Press enter to continue"
-< There are at least two solutions you can try:
-
- - press q once and Vim should stop asking
- - set auto_install = 1 (to make Vim stop asking you any questions. However you
- won't know if knew dependencies are fetched in that case etc)
-
-
- Example how to patch vcs checkout functions (eg if you're behind a proxy and
- need to checkout github urls by http://): >
- let g:vim_addon_manager = {'scms': {'git': {}}}
- fun! MyGitCheckout(repository, targetDir)
- let a:repository.url = substitute(a:repository.url, '^git://github', 'http://github', '')
- return vam#utils#RunShell('git clone --depth=1 $.url $p', a:repository, a:targetDir)
- endfun
- let g:vim_addon_manager.scms.git.clone=['MyGitCheckout']
-<
-
- Another example: replace git_update and show changelog >
- let g:vim_addon_manager = {'scms': {'git': {}}}
- fun! MyGitUpdate(targetDir)
- let cd = shellescape
- let oldHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
- call vam#utils#RunShell('cd $p && git pull', a:targetDir)
- let newHash = vam#utils#System('git --git-dir=$p/.git rev-list HEAD -1', a:targetDir)
- if oldHash isnot# newHash
- silent enew
- setlocal buftype=nofile bufhidden=wipe
- call setline(1, a:targetDir)
- call append(1, split(system(vam#utils#ShellDSL('cd $; git log $[]..$[]', a:targetDir, oldHash, newHash)), "\n"))
- endif
- return 0
- endfun
- let g:vim_addon_manager.scms.git.update=['MyGitUpdate']
-<
-
- HOWTO benchmark startup? >
- vim --startuptime logfile -c q
-< Then read the logfile. As alternative you can benchmark activating scripts
- *at rurntime* by >
- tlib#cmd#Time('call vam#ActivateAddons(["A"])')
-< which requires tlib. Why at runtime? Because plugin/*.vim files are sourced
- by VIM after .vimrc has been processed
-
-------------------------------------------------------------------------------
-2.2 Names of addons and addon sources *VAM-addon-names*
-
-Because we are human VAM uses readable names as unique identifier for plugins.
-Those identifieres (= plugin names) are passed to |vam#ActivateAddons()|, |:InstallAddons|,
-|:ActivateAddons| . The name is automatically derived from plugin titles at
-www.vim.org.
-
-types of names:
- 1) Plugin name looked up in pool. Try |:AddonInfo| NAME
-
- Determining addon names ~
- - From ID: |:AddonsInfo| SCRIPT_ID, pick the word right after string "Plugin: ".
- - use |:InstallAddons|' name completion by typing some chars then pressing
- <c-d> then <tab>.
- - Use <c-x><c-p> completion while editing your vimrc.
-
- 2) Name which gets rewritten internally (see |vam#install#RewriteName()|) >
- github:{Name} => {"type": "git", "url": "git://github.com/{Name}/vim-addon-{Name}}
- github:{N}/{Repo} => {"type": "git", "url": "git://github.com/{N}/{Repo}"}
- git:{GIT_URL} => {"type": "git", "url": "GIT_URL"}
-< Don't use if you expect others to create plugins depending on yours. Add
- your plugin to |VAM-kr| instead.
-
-
-Instead of telling us to add your plugin to |VAM-kr| you can also patch the
-pool easily: |VAM-kr-patching| - however if you contribute to |VAM-kr| the
-community will benefit much more.
-
-*VAM-kr* is the default pool. VAM checks it out by default. Its long name is
-*vim-addon-manager-known-repositories* (stored in |VAM-known| option).
-
-*VAM-kr-patching*
-VAM-kr merges both sources (scm and www.vim.org ones), see |VAM-MergeSources|.
-The result is provided by vam_known_repositories#Pool() which is the only pool
-used by default. See example and default implementation vam#install#Pool().
-
-If you want to add your own soucres consider submitting them to
-VAM-kr as patch. If you don't there are two ways:
-
-WAY 1: (still supported) add to your .vimrc before activating VAM (BUG/TODO [5]): >
- let g:vim_addon_manager = {}
- let g:vim_addon_manager.plugin_sources = {}
- let g:vim_addon_manager.plugin_sources['your_plugin_name'] = { plugin dictionary }
-<
-WAY 2: define your own Pool function: >
- let g:vim_addon_manager = {}
- let g:vim_addon_manager.pool_fun = function('MyPoolFun')
- fun MyPoolFun()
- let d = vam#install#Pool()
- let d['my_plugin'] = { 'type' : 'git', 'url' : ' ... ' }
- return d
- endf
-
-Plugin dictionaries are described in |addon-info-repository|.
-
-Example: overwriting the MergeSources function (VAM-kr pool implementation): >
-Yes, you can do this in MyPoolFun shown above as well >
-
- fun! vam_known_repositories#MergeSources(plugin_sources, www_vim_org, scm_plugin_sources, patch_function, snr_to_name)
-
- " run default:
- call vam_known_repositories#MergeSources(a:plugin_sources, a:www_vim_org, a:scm_plugin_sources, a:patch_function, a:snr_to_name)
-
- " patch sources the way you like. This example adds username and password
- " for SVN repositories. As alternative you could overwrite git urls etc ..
- for your_plugin in ['svn-driven-key1', ...]
- let a:plugin_sources[your_plugin]['username'] = 'svn user'
- let a:plugin_sources[your_plugin]['password'] = 'svn user'
- endfor
-
- let a:plugin_sources['your_plugin_name'] = { plugin dictionary }
- endf
- " tell VAM to use your MergeSources function:
- let g:vim_addon_manager = {}
- let g:vim_addon_manager['MergeSources'] = function('MyMergeSources')
-<
-
-
-------------------------------------------------------------------------------
-2.3 Example: configurable setup *VAM-complex-setup-sample*
->
- call vam#ActivateAddons(["github:YOURNAME"],{'auto_install' : 0})
- " this initializes Vim the way *you* want also loading more plugins:
- call vim_addon_YOURNAME#Activate(['c-dev','ruby-dev'])
-<
- My implementation looks like this:
- https://github.com/MarcWeber/vim-addon-MarcWeber/blob/master/autoload/vim_addon_MarcWeber.vim
-
- You can then load plugins depending on env vars:
- Example: >
- call vim_addon_YOURNAME#Activate(['always']+split($V,','))
-< Then you can run vim like this from shell >
- V=c-dev,ruby-dev vim
-<
- This section was written to inspire you only.
-
-------------------------------------------------------------------------------
-2.4 Unattended installation *VAM-unattended-installation*
-
-Note: You should always review foreign code before running it. That said this
-is how you can update or install unattended (without confirmations ..):
-
- redir! > /tmp/log-vim.txt
- silent! ACTION
- messages
-
-where ACTION is either UpdateActivatedAddons or vam#InstallAddons()
-
-This works for http://mawercer.de/~marc/vam/index.php.
-
-There is also the undocumented g:vim_addon_manager.dont_source option which
-should be used if you want to checkout eventually untrusted code! If you're
-going to use the plugins anyway its of no use.
-You may also want to set auto_install.
==============================================================================
3. Functionality provided *VAM-functionality*
@@ -1037,8 +716,11 @@ If you want something like this to happen contact me.
==============================================================================
11. Some notes for Gentoo users *VAM-gentoo*
-Gentoo users may consider installing this plugin from pluginloader overlay
-which is accessible via mercurial, url:
+ZyX packaged vim-addon-manager for gentoo. Eventually you still prefer using
+SetupVAM because it works on any unix like system - and its files are that
+small so its debatable whether its worth sharing.
+
+The overlay is accessible via mercurial, url:
http://vimpluginloader.hg.sourceforge.net:8000/hgroot/vimpluginloader/pluginloader-overlay
In order to use this overlay paludis users can add the pluginloader.conf file
Oops, something went wrong.

4 comments on commit ca3b3c9

Collaborator

ZyX-I replied Apr 12, 2012

By the way, what is the reason for this “improvement”? I see only disadvantages:

  1. Now there are two files for searching for documentation.
  2. In most projects documentation is located only in doc/project-name.txt, or there is at least a file with this name.
  3. Nobody reads full documentation, especially when there is a TOC. TOC here was split in two files which makes anything hard to reach.
  4. Sections moved to getting started were already at the start.
  5. If somebody measures complexity of the script by documentation then having two documentation files will make complexity bigger because you now have more lines and, like I said, not so complex projects do not have more then one documentation file. Need for a split on its own increases seen complexity, even if two files are empty.

My suggestion: there is a wiki on github. Move “Testing”, “notes for windows users”, “notes for Gentoo users”, “design notes”, “Troubleshooting”, “VAM vs”, “Tracking down errors”, “Making plugins work with VAM” and also most of code from “Installation” there (last can be put to sample-vimrc-for-new-users, though I personally would move it to wiki completely as it has nothing to do with files needed for VAM). There is also issue tracker on github, move “known bugs”, “TODO” notes there (or, better, move it to bitbucket bug tracker, it is not a problem to setup a mirror there. Bug tracker is not the strong side of github: you can’t mark an issue a “enhancement”, for example). Then documentation will contain only what it should: intro, functionality description.

Owner

MarcWeber replied Apr 12, 2012

Collaborator

ZyX-I replied Apr 13, 2012

What is the difference between syncing repo and wiki or txt file? I even saw a plugin that makes you able to edit wiki pages in vim (though I do not remember which wiki was it).

And can you tell, did those people say that splitting docs into two parts reduced seen complexity? Because documentation size was not reduced, it was increased instead. Essential part is on www.vim.org and in github README — there is everything is needed to start. I can’t say that section “Installation” being 264 lines long with big bundles of unhighlighted code (which makes it hard to say how much code is there and how much comments) will make visible complexity less, no matter where it is located.

// It is probably a good idea to setup a cron job that will in addition to posting bundles to www.vim.org also sync page contents. I have a similar one that pushes help Intro section to README file, mercurial wiki and www.vim.org.

Owner

MarcWeber replied Apr 13, 2012

Please sign in to comment.