Re: Packages

5e39757c53cc6e77635ddfbea0aa9b6a8c0077a4
runtime/doc/options.txt | 3 ++-
runtime/doc/repeat.txt | 33 ++++++++++++++++++++++-----------
2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 09518c0..5945297 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -5403,7 +5403,8 @@ A jump table for the options with a short description can be found at |Q_op|.
*'packpath'* *'pp'*
'packpath' 'pp' string (default: see 'runtimepath')
{not in Vi}
- Directories used to find packages. See |packages|.
+ Directories that are searched for a "pack" directory where |packages|
+ can be added.


*'paragraphs'* *'para'*
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index 1b9e54f..985ffac 100644
--- a/runtime/doc/repeat.txt
+++ b/runtime/doc/repeat.txt
@@ -419,23 +419,30 @@ Rationale:

A Vim package is a directory that contains one or more plugins. The
advantages over normal plugins:
-- A package can be downloaded as an archive and unpacked in its own directory.
- That makes it easy to updated and/or remove.
-- A package can be a git, mercurial, etc. repository. That makes it really
- easy to update.
+- A package, or plugins within the package, can be downloaded as an archive
+ and unpacked in its own directory. That makes it easy to update and/or
+ remove the entire package or individual plugins.
+- A package or any of its plugins can be a git, mercurial, etc. repository.
+ That makes it really easy to update.
- A package can contain multiple plugins that depend on each other.
-- A package can contain plugins that are automatically loaded on startup and
- ones that are only loaded when needed with `:loadplugin`.
+- A package can contain plugins that are automatically loaded on startup, and
+ plugins that are only loaded when needed with `:packadd`.

-Let's assume your Vim files are in the "~/.vim" directory and you want to add a
-package from a zip archive "/tmp/mypack.zip":
+Vim will search for packages inside any "pack" directory listed in the
+|'packpath'| option.
+
+Let's assume your Vim files are in the "~/.vim" directory and you want to add
+a package from a zip archive "/tmp/mypack.zip":
% mkdir -p ~/.vim/pack/my
% cd ~/.vim/pack/my
% unzip /tmp/mypack.zip

-The directory name "my" is arbitrary, you can pick anything you like.
+Here you create a directory "my" to contain your package. The directory name
+"my" is arbitrary, you can use anything you like.

-You would now have these files under ~/.vim:
+Assume your package contains two plugins: "always" and "mydebug". You always
+want "always" to be enabled, but you will only load "mydebug" on demand. You
+would now have these files under ~/.vim:
pack/my/README.txt
pack/my/ever/always/plugin/always.vim
pack/my/ever/always/syntax/always.vim
@@ -447,6 +454,10 @@ directory level:
% cd ~/.vim/pack/my/ever/always
% unzip /tmp/myplugin.zip

+Note that plugins you always want to enable must be placed in an "ever"
+directory under your package, whereas plugins you enable on demand go in an
+"opt" directory so that |:packadd| can find them. See |pack-add| below.
+
When Vim starts up it scans all directories in 'packpath' for plugins under the
"ever" directory and loads them. When found that directory is added to
'runtimepath'.
@@ -460,7 +471,7 @@ find the syntax/always.vim file, because its directory is in 'runtimepath'.
Vim will also load ftdetect files, like with |:packadd|.

*pack-add*
-To load an optional plugin from a pack use the `:packadd` command: >
+To load an optional plugin from a package use the `:packadd` command: >
:packadd mydebug
This could be done inside always.vim, if some conditions are met.
Or you could add this command to your |.vimrc|.

On Sat, Mar 5, 2016 at 7:27 AM, Bram Moolenaar <Bram@moolenaar.net> wrote:
>
>
> Ben Fritz wrote:
> >
> > For Pathogen, you install by unzipping all files for a plugin, into a
> > directory under "bundle":
> >
> >     ~/.vim/bundle/someplugin/plugin/foo.vim
> >     ~/.vim/bundle/someplugin/autoload/bar.vim
> >     ~/.vim/bundle/someplugin/syntax/beez.vim
> >
> > With packages, the default 'packpath' is the same as runtimepath. The
> > example code creates a ~/.vim/pack/my/always directory. Is "always"
> > synonymous with "someplugin" above? I.e. is "always" what you'd get
> > from cloning an existing plugin not designed specifically for a
> > packages setup?
>
> "always" is just a name.  You got the directory name wrong.  I renamed
> to avoid confusion.  So now for one plugin:
>
> If you don't have a package but a single plugin, you need to create the extra
> directory level:
>         % mkdir -p ~/.vim/pack/my/ever/something
>         % cd ~/.vim/pack/my/ever/something
>         % unzip /tmp/myplugin.zip
>
> You would now have these files:
>         pack/my/ever/something/plugin/foo.vim
>         pack/my/ever/something/syntax/some.vim
>

I don't see this reflected in the help yet. I think the name "always" is fine if it is explained.

I attached a patch that does this explaining and clears up a few other points of confusion I had.

Also it changes ":loadplugin" to ":packadd" because ":loadplugin" doesn't seem to exist anymore.

See attached.

> > What's "my" for? Is that the way to package multiple plugins together?
> > Is it necessary or can "someplugin" go directly under "pack"? The help
> > just mentions looking for an "ever" directory, it doesn't talk about
> > any intervening directories.
>
> "my" is the name of the package that you choose.  As the help says:
>
> The directory name "my" is arbitrary, you can pick anything you like.
>

Thanks, that was another point of confusion I had. I didn't even realize "my" was the package name.

> > You talked about dependencies...with this method, won't you
> > potentially have multiple copies of every dependency, if every plugin
> > that has a dependency defines a package instead to bundle the plugin
> > with all its dependencies?
>
> I would expect people who create several plugins that depend on a common
> library to have one package with all these plugins.
>

Ah, so this would be where true plugin managers come in. A plugin manager could be expected to track the dependencies between multiple plugins and create a package for all related plugins in a group.

> > From the help for 'packpath' I expected every directory under ~/.vim
> > and ~/.vim/after to be searched recursively for an "ever" directory. I
> > don't see anything special about the "pack" directory in the help, but
> > just putting a new "ever" directory under my existing "bundles" and
> > moving anything inside doesn't seem to do anything. Is it because I
> > need a "my" directory of some kind? Or is "pack" actually special? How
> > does 'packpath' relate to this?
>
> All packages go under "pack".
>

OK, "pack" was never mentioned explicitly, only in examples, so I described it as I currently understand it.

Please correct me if I'm wrong.

--
--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

---
You received this message because you are subscribed to the Google Groups "vim_use" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_use+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.