Skip to content

Commit

Permalink
Improved documentation:
Browse files Browse the repository at this point in the history 
- Fixed section numbers
- Moved 2.10. to 16.1.
- Some other fixes (wording and typos)
  • Loading branch information
@ZyX-I
ZyX-I committed Dec 8, 2012
1 parent 9d0a772 commit 5599204
Show file tree
Hide file tree
Showing 2 changed files with 129 additions and 129 deletions.
101 changes: 77 additions & 24 deletions doc/vim-addon-manager-additional-documentation.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,31 @@
CONTENTS *VAM-contents-additional*

In |vim-addon-manager-getting-started.txt|:
1. Intro |VAM-intro|
2. Installation & installing plugins |VAM-installation|
2.2 Names of addons and addon sources |VAM-addon-names|
2.3 Example: configurable setup |VAM-complex-setup-sample|
2.4 unattended installation |VAM-unattended-installation|
1. Intro |VAM-intro|
2. Installation & installing plugins |VAM-installation|
2.2. Names of addons and addon sources |VAM-addon-names|
2.3. Example: configurable setup |VAM-complex-setup-sample|
2.4. unattended installation |VAM-unattended-installation|
2.5. Searching the plugins |VAM-plugins-search|
Here:
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
4. Options |VAM-options|
6. Uninstalling plugins |VAM-uninstall-plugins|
7. Addon-info file |VAM-addon-info|
8. Author, credits, some notes |VAM-related|
9. Testing this plugin |VAM-testing|
10. Some notes for windows users |VAM-windows|
11. Some notes for Gentoo users |VAM-gentoo|
12. Troubleshooting and known bugs |VAM-trouble-shooting|
12.1. Common error messages |VAM-common-errors|
13. TODO notes |VAM-TODO|
14. VAM vs ... |VAM-comparison|
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
17. VAM runtimepath handling tricks |VAM-rtp-tricks|
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
4. Options |VAM-options|
6. Uninstalling plugins |VAM-uninstall-plugins|
7. Addon-info file |VAM-addon-info|
8. Author, credits, some notes |VAM-related|
9. Testing this plugin |VAM-testing|
10. Some notes for windows users |VAM-windows|
11. Some notes for Gentoo users |VAM-gentoo|
12. Troubleshooting and known bugs |VAM-trouble-shooting|
12.1. Common error messages |VAM-common-errors|
13. TODO notes |VAM-TODO|
14. VAM vs ... |VAM-comparison|
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
16.1. The perfect plugin |VAM-plugin-guide|
17. VAM runtimepath handling tricks |VAM-rtp-tricks|

==============================================================================
3. Functionality provided *VAM-functionality*
Expand Down Expand Up @@ -851,10 +853,10 @@ what's going to happen.
12. Troubleshooting and known bugs *VAM-trouble-shooting*

[BUG 101] Directories with commas are not supported.
Any discussion is here: https://github.com/MarcWeber/vim-addon-manager/issues/101
Any discussion is here: https://github.com/MarcWeber/vim-addon-manager/issues/101

[BUG 10] Think about how to integrate ideas found in ipi
http://www.vim.org/scripts/script.php?script_id=3809
http://www.vim.org/scripts/script.php?script_id=3809

Runtimepath manipulation should be separated from installation / update
logic. This way you can have different implementation for updating plugins
Expand Down Expand Up @@ -1229,6 +1231,57 @@ Filetype detection files (from ftdetect/ directory) are loaded if you set
"filetype on". Thus if you do it after last call to vam#ActivateAddons,
everything should be fine.

------------------------------------------------------------------------------
16.1. The perfect plugin *VAM-plugin-guide*


Well - this should not be here either - and its only "my personal view on it".

useful plugins for developing in VimL: vim-dev and reload.

plugin/NAME.vim

is sourced always. Thus it should only contain the user interface
configuration and code which is always used anyway (autocommands, mappings,
commands).

autoload/NAME.vim

is loaded as needed. It should contain the remaining code.

syntax/
contains syntax files.

ftdetect/
contains rules to assign file types to files.

colors/
contains color schemes.

You may want to use :h plugin or :helpgrep to find details in the Vim help.

I personally don't like globbering the golbal namespace with >
if !exists(g:my_plugin_width')
let g:my_plugin_width = 20
endif
because it is harder to read (3 lines). Historically Vim did not support
dictionaries, so using g:foo{'var'} = value was the only way. Today Vim
supports dictionaries which is why I personally prefer the “bind global named
dictionary to a short local s: var”. VAM itself shows how to do it (grep for
s:c) Almost of all of my plugins follow these rules.

common rules:
- rather be simple than complicated
- follow the principle of least surprise
- try to find an existing plugin, join.
- if you have to write from scratch document why
- consider referencing related projects which do similar things.
After all we're a community and our task is to keep it healthy
thus to provide value to each other.
- ...


==============================================================================
17. VAM runtimepath handling tricks *VAM-rtp-tricks*
Expand Down
157 changes: 52 additions & 105 deletions doc/vim-addon-manager-getting-started.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,32 @@ CONTENTS *VAM-contents-getting-started*

0. GETTING STARTED & LOOKING FOR HELP <<

1. Intro |VAM-intro|
2. Installation & installing plugins |VAM-installation|
2.2 Names of addons and addon sources |VAM-addon-names|
2.3 Example: configurable setup |VAM-complex-setup-sample|
2.4 Unattended installation |VAM-unattended-installation|

2.8 How to find the plugin getting your job done?
1. Intro |VAM-intro|
2. Installation & installing plugins |VAM-installation|
2.2. Names of addons and addon sources |VAM-addon-names|
2.3. Example: configurable setup |VAM-complex-setup-sample|
2.4. Unattended installation |VAM-unattended-installation|
2.5. Searching the plugins |VAM-plugins-search|
2.9 error messages you may see and what they mean
2.10 The perfect plugin
In |vim-addon-manager-additional-documentation.txt|:
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
4. Options |VAM-options|
6. Uninstalling plugins |VAM-uninstall-plugins|
7. Addon-info file |VAM-addon-info|
8. Author, credits, some notes |VAM-related|
9. Testing this plugin |VAM-testing|
10. Some notes for windows users |VAM-windows|
11. Some notes for Gentoo users |VAM-gentoo|
12. Troubleshooting and known bugs |VAM-trouble-shooting|
12.1. Common error messages |VAM-common-errors|
13. TODO notes |VAM-TODO|
14. VAM vs ... |VAM-comparison|
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
17. VAM runtimepath handling tricks |VAM-rtp-tricks|
3. Functionality provided |VAM-functionality|
3.1. Commands |VAM-commands|
3.2. Functions |VAM-functions|
4. Options |VAM-options|
6. Uninstalling plugins |VAM-uninstall-plugins|
7. Addon-info file |VAM-addon-info|
8. Author, credits, some notes |VAM-related|
9. Testing this plugin |VAM-testing|
10. Some notes for windows users |VAM-windows|
11. Some notes for Gentoo users |VAM-gentoo|
12. Troubleshooting and known bugs |VAM-trouble-shooting|
12.1. Common error messages |VAM-common-errors|
13. TODO notes |VAM-TODO|
14. VAM vs ... |VAM-comparison|
15. Tracking down errors |VAM-tracking-down-erros|
16. Making plugins work with VAM |VAM-adjusting-plugins|
16.1. The perfect plugin |VAM-plugin-guide|
17. VAM runtimepath handling tricks |VAM-rtp-tricks|

==============================================================================

Expand Down Expand Up @@ -305,7 +304,7 @@ NOTES: ~
better to read |profiling| instead.

------------------------------------------------------------------------------
2.2 Names of addons and addon sources *VAM-addon-names*
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()|,
Expand Down Expand Up @@ -387,7 +386,7 @@ Yes, you can do this in MyPoolFun shown above as well >


------------------------------------------------------------------------------
2.3 Example: configurable setup *VAM-complex-setup-sample*
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:
Expand All @@ -405,7 +404,7 @@ Yes, you can do this in MyPoolFun shown above as well >
This section was written to inspire you only.

------------------------------------------------------------------------------
2.4 Unattended installation *VAM-unattended-installation*
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 ..):
Expand Down Expand Up @@ -457,30 +456,32 @@ just use the log_buffer_name option which defaults to a value of
\}
<
------------------------------------------------------------------------------
2.8 How to find the plugin getting your job done?

its not the task of VAM telling you - I know about the following possibilities:
1) use www.vim.org/search.php because still most plugins are also on
www.vim.org
2) Try google and github search (this time including "vim" as keyword) because
most plugins are hosted @ github today
3) There is vim.wikia.com Use its search
4) of course there are google/bing/(any other web) search
5) There are mailinglists

Why doesn't VAM support a search?
- Because we still want you to visit vim's website (its a charity project after all)
- Because we like the linux philosophy: One tool should do one task well and
be responsible for that only. VAM is only responsible for isntaling and
activating plugins thus for recreating your work environment form scratch.
2.5. Searching the plugins *VAM-plugins-search*

VAM does not support searching plugins; you have to use one of the other
options. Common ones:
1. use www.vim.org/search.php because still most plugins are also on
www.vim.org.
2. Try google and github search (this time including "vim" as keyword) because
most plugins are hosted on github today.
3. There is vim.wikia.com. Use its search.
4. Of course, there are google/bing/(any other web) search.
5. There are mailinglists.

VAM does not support a search …
- Because we still want you to visit vim's website (its a charity project
after all).
- Because we like the linux philosophy: One tool should do one task well and
be responsible for that only. VAM is only responsible for isntaling and
activating plugins thus for recreating your work environment form scratch.
Thus this should be a "plugin" providing such a feature, not VAM.
- Its not that easy. If you want to work on it get in touch, because there are
multiple sources today unfortunately.
Of course we could just dump the information from www.vim.org and allow you
to grep it. I just think the whole plugin system on www.vim.org should be
rewritten allowing github urls. I haven't had time to do it yet.
I've been trying to do it for more than 12 month and failed due to lack of time.
If you want to sponsor such an effort get in touch.
- It is not that easy. If you want to work on it get in touch, because there
are multiple sources today unfortunately. Of course we could just dump the
information from www.vim.org and allow you to grep it. I just think the
whole plugin system on www.vim.org should be rewritten allowing github urls.
I haven't had time to do it yet. I've been trying to do it for more than 12
month and failed due to lack of time. If you want to sponsor such an effort
get in touch.

------------------------------------------------------------------------------
2.9 error messages you may see and what they mean
Expand All @@ -495,58 +496,4 @@ The long description is that vam# functions are looked up in
&runtimepath/autoload/vam.vim files. If Vim doesn't find such the error will
happen


------------------------------------------------------------------------------
2.10 The perfect plugin


Well - this should not be here either - and its only "my personal view on it".

useful plugins for developing in VimL: vim-dev and reload.

plugin/NAME.vim

Is sourced always. Thus it should only contain the user interface
configuration and code which is always used anyway (auto commands etc)

plugin/autoload/NAME.vim

Is loaded as needed. It should contain the remaining code

syntax/
contains syntax files

ftdetect/
contains rules to assign file types to files

colors/
contains color schemes

You may want to use :h plugin or :helpgrep to find details in the Vim help.

I personally don't like globbering the golbal namespace with

if !exists(g:my_plugin_width')
let g:my_plugin_width = 20
endif

Because its harder to read (3 lines). Historically Vim did not support
dictionaries, so using g:foo{'var'} = value was the only way. Today Vim
supports dictionaries which is why I personally prefer the "bind global named
dictionary to a short local s: var. VAM itself shows how to do it (grep for
s:c) Almost of all of my plugins follow these rules.

common rules:
- rather be simple than complicated
- follow the principle of least surprise
- try to find an existing plugin, join.
- if you have to write from scratch document why
- consider referencing related projects which do similar things.
After all we're a community and our task is to keep it healthy
thus to provide value to each other.
- ...

TODO: think about moving this section to
doc/vim-addon-manager-additional-documentation.txt

vim: tw=78:ts=8:ft=help:norl

0 comments on commit 5599204

Please sign in to comment.