From 4dfd36e157c67334f4d44f9b20a57b755443dc97 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Fri, 28 Jul 2023 12:03:10 +0300
Subject: [PATCH] docs: document extraPlugins usage and add missing
 documentation entries

---
 docs/manual/custom-plugins.adoc | 33 +++++++++++++++++++++++++++++++-
 docs/manual/home-manager.adoc   | 34 ---------------------------------
 docs/release-notes/rl-0.5.adoc  | 12 ++++++++----
 3 files changed, 40 insertions(+), 39 deletions(-)

diff --git a/docs/manual/custom-plugins.adoc b/docs/manual/custom-plugins.adoc
index 642b60e..6f6da92 100644
--- a/docs/manual/custom-plugins.adoc
+++ b/docs/manual/custom-plugins.adoc
@@ -3,11 +3,42 @@
 
 You can use custom plugins, before they are implemented in the flake.
 To add a plugin, you need to add it to your config's `config.vim.startPlugins` array.
-This is an example of adding the FrenzyExists/aquarium-vim plugin:
+
+
+=== New Method
+As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
+
+Instead of using DAGs exposed by the library, you may use the extra plugin module as follows:
 
 [source,nix]
 ----
 {
+  config.vim.extraPlugins = with pkgs.vimPlugins; {
+    aerial = {
+      package = aerial-nvim;
+      setup = ''
+        require('aerial').setup {
+          -- some lua configuration here
+        }
+      '';
+    };
+    
+    harpoon = {
+      package = harpoon;
+      setup = "require('harpoon').setup {}";
+      after = ["aerial"];
+    };
+  };
+}
+----
+
+=== Old Method
+Users who have not yet updated to 0.5, or prefer a more hands-on approach may use the old method where the load orderof the plugins is determined by DAGs.
+
+[source,nix]
+----
+{
+  # fetch plugin source from GitHub and add it to startPlugins
   config.vim.startPlugins = [
     (pkgs.fetchFromGitHub {
       owner = "FrenzyExists";
diff --git a/docs/manual/home-manager.adoc b/docs/manual/home-manager.adoc
index a937738..df60652 100644
--- a/docs/manual/home-manager.adoc
+++ b/docs/manual/home-manager.adoc
@@ -43,38 +43,4 @@ Then we should be able to use the given module. E.g.
 }
 ----
 
-=== Custom vim/neovim plugins
 
-It is possible to add custom plugins to your configuration by using the `vim.startPlugins` option and the this flake's lua DAG library. 
-
-Start by adding it to startPlugins. This example uses nvim-surround, but the process will be similar for other plugins as well.
-
-[source,nix]
-----
-{
-  programs.neovim-flake = {
-    enable = true;
-    settings = {
-      vim.startPlugins = [ pkgs.vimPlugins.nvim-surround ];
-    };
-  };
-}
-----
-
-Followed by requiring the plugin, should it need one, in the lua DAG. Please note that you're able to name the DAG to however you want, the name will add a `--SECTION <name>` in the init.vim, under which it will be initialized. `lib.nvim.dag.entryAfter ["name"]` could also be used to initialize a plugin only after a previous plugin has beeni initialize
-Your final setup will likely look like this, where nvim-flake refers to your flake input or fetch.
-
-[source,nix]
-----
-{
-  programs.neovim-flake = {
-    enable = true;
-    settings = {
-      vim.startPlugins = [ pkgs.vimPlugins.nvim-surround ];
-      luaConfigRC.nvim-surround = nvim-flake.lib.nvim.dag.entryAnywhere '' # nvim-flake is a reference to the flake. Please change this accordingly to your config.
-        require("nvim-surround").setup()
-      '';
-    };
-  };
-}
-----
diff --git a/docs/release-notes/rl-0.5.adoc b/docs/release-notes/rl-0.5.adoc
index 865ee3f..cde1d4b 100644
--- a/docs/release-notes/rl-0.5.adoc
+++ b/docs/release-notes/rl-0.5.adoc
@@ -8,14 +8,18 @@
 
 https://github.com/horriblename[horriblename]:
 
-* Add transparency support for tokyonight theme.
+* Added transparency support for tokyonight theme.
 
-* Fix bug where cmp's close and scrollDocs mappings wasn't working.
+* Fixed a bug where cmp's close and scrollDocs mappings wasn't working.
+
+* Streamlined and simplified extra plugin API with the addition of <<opt-vim.extraPlugins>>.
 
 https://github.com/amanse[amanse]:
 
-* Add daily notes options for obsidian plugin
+* Added daily notes options for obsidian plugin.
 
 https://github.com/notashelf[notashelf]:
 
-* Add GitHub Copilot to completion sources
+* Added GitHub Copilot to completion sources.
+
+* Added <<opt-vim.ui.borders>> for global and individual plugin border configuration.