docs(pack): add plugin hooks example

Problem: No examples of how to use `PackChanged[Pre]` for plugin hooks.

Solution: Add examples of creating plugin hooks.

runtime/doc/pack.txt

@@ -301,11 +301,37 @@ Available events to hook into ~
 
 Each event populates the following |event-data| fields:
 • `active` - whether plugin was added via |vim.pack.add()| to current session.
-• `kind` - one of "install" (install on disk), "update" (update existing
+• `kind` - one of "install" (install on disk; before loading), "update"
-  plugin), "delete" (delete from disk).
+  (update already installed plugin; might be not loaded), "delete" (delete
+  from disk).
 • `spec` - plugin's specification with defaults made explicit.
 • `path` - full path to plugin's directory.
 
+These events can be used to execute plugin hooks. For example: >lua
+    local hooks = function(ev)
+      -- Use available |event-data|
+      local name, kind = ev.data.spec.name, ev.data.kind
+
+      -- Run build script after plugin's code has changed
+      if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+        vim.system({ 'make' }, { cwd = ev.data.path })
+      end
+
+      -- If action relies on code from the plugin (like user command or
+      -- Lua code), make sure to explicitly load it first
+      if name == 'plug-2' and kind == 'update' then
+        if not ev.data.active then
+          vim.cmd.packadd('plug-2')
+        end
+        vim.cmd('PlugTwoUpdate')
+        require('plug2').after_update()
+      end
+    end
+
+    -- If hooks need to run on install, run this before `vim.pack.add()`
+    vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
+<
+
 
 *vim.pack.Spec*
 

runtime/lua/vim/pack.lua

@@ -91,17 +91,44 @@
 ---- Use |vim.pack.del()| with a list of plugin names to remove. Make sure their specs
 ---are not included in |vim.pack.add()| call in 'init.lua' or they will be reinstalled.
 ---
---- Available events to hook into ~
+---Available events to hook into ~
 ---
---- - [PackChangedPre]() - before trying to change plugin's state.
+---- [PackChangedPre]() - before trying to change plugin's state.
---- - [PackChanged]() - after plugin's state has changed.
+---- [PackChanged]() - after plugin's state has changed.
 ---
---- Each event populates the following |event-data| fields:
+---Each event populates the following |event-data| fields:
---- - `active` - whether plugin was added via |vim.pack.add()| to current session.
+---- `active` - whether plugin was added via |vim.pack.add()| to current session.
---- - `kind` - one of "install" (install on disk), "update" (update existing
+---- `kind` - one of "install" (install on disk; before loading),
---- plugin), "delete" (delete from disk).
+---  "update" (update already installed plugin; might be not loaded),
---- - `spec` - plugin's specification with defaults made explicit.
+---  "delete" (delete from disk).
---- - `path` - full path to plugin's directory.
+---- `spec` - plugin's specification with defaults made explicit.
+---- `path` - full path to plugin's directory.
+---
+--- These events can be used to execute plugin hooks. For example:
+---```lua
+---local hooks = function(ev)
+---   -- Use available |event-data|
+---   local name, kind = ev.data.spec.name, ev.data.kind
+---
+---   -- Run build script after plugin's code has changed
+---   if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+---     vim.system({ 'make' }, { cwd = ev.data.path })
+---   end
+---
+---   -- If action relies on code from the plugin (like user command or
+---   -- Lua code), make sure to explicitly load it first
+---   if name == 'plug-2' and kind == 'update' then
+---     if not ev.data.active then
+---       vim.cmd.packadd('plug-2')
+---     end
+---     vim.cmd('PlugTwoUpdate')
+---     require('plug2').after_update()
+---   end
+---end
+---
+----- If hooks need to run on install, run this before `vim.pack.add()`
+---vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
+---```
 
 local api = vim.api
 local uv = vim.uv