docs: clarify wording; add examples and remove redundancies

docs/manual/configuring/custom-plugins/configuring.md

@@ -1,13 +1,20 @@
 # Configuring {#sec-configuring-plugins}
 
 Just making the plugin to your Neovim configuration available might not always
-be enough. In that case, you can write custom lua config using either
-`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or
-`config.vim.luaConfigRC`.
+be enough., for example, if the plugin requires a setup table. In that case, you
+can write custom Lua configuration using one of
 
-The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule`
-and `setupOpt` can be used if the plugin uses a `require('module').setup(...)`
-pattern. Otherwise, the `before` and `after` hooks should do what you need.
+- `config.vim.lazy.plugins.*.setupOpts`
+- `config.vim.extraPlugins.*.setup`
+- `config.vim.luaConfigRC`.
+
+## Lazy Plugins {#ch-vim-lazy-plugins}
+
+`config.vim.lazy.plugins.*.setupOpts` is useful for lazy-loading plugins, and
+uses an extended version of `lz.n's` `PluginSpec` to expose a familiar
+interface. `setupModule` and `setupOpt` can be used if the plugin uses a
+`require('module').setup(...)` pattern. Otherwise, the `before` and `after`
+hooks should do what you need.
 
 ```nix
 {
@@ -25,7 +32,9 @@ pattern. Otherwise, the `before` and `after` hooks should do what you need.
 }
 ```
 
-The second option uses an attribute set, which maps DAG section names to a
+## Standard API {#ch-vim-extra-plugins}
+
+`vim.extraPlugins` uses an attribute set, which maps DAG section names to a
 custom type, which has the fields `package`, `after`, `setup`. They allow you to
 set the package of the plugin, the sections its setup code should be after (note
 that the `extraPlugins` option has its own DAG scope), and the its setup code
@@ -48,29 +57,36 @@ respectively. For example:
 }
 ```
 
-The third option also uses an attribute set, but this one is resolved as a DAG
+### Setup using luaConfigRC {#setup-using-luaconfigrc}
+
+`vim.luaConfigRC` also uses an attribute set, but this one is resolved as a DAG
 directly. The attribute names denote the section names, and the values lua code.
 For example:
 
 ```nix
 {
-  # this will create an "aquarium" section in your init.lua with the contents of your custom config
-  # which will be *appended* to the rest of your configuration, inside your init.vim
+  # This will create a section called "aquarium" in the 'init.lua' with the
+  # contents of your custom configuration. By default 'entryAnywhere' is implied
+  # in DAGs, so this will be inserted to an arbitrary position. In the case you 
+  # wish to control the position of this section with more precision, please
+  # look into the DAGs section of the manual.
   config.vim.luaConfigRC.aquarium = "vim.cmd('colorscheme aquiarum')";
 }
 ```
 
 <!-- deno-fmt-ignore-start -->
+[DAG system]: #ch-using-dags
+[DAG section]: #ch-dag-entries
 
 ::: {.note}
-One of the greatest strengths of nvf is the ability to order
-snippets of configuration via the DAG system. It will allow specifying positions
-of individual sections of configuration as needed. nvf provides helper functions
+One of the **greatest strengths** of **nvf** is the ability to order
+configuration snippets precisely using the [DAG system]. DAGs
+are a very powerful mechanism that allows specifying positions
+of individual sections of configuration as needed. We provide helper functions
 in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may
 use.
 
-Please refer to the [DAG section](#ch-dag-entries) in the nvf manual
+Please refer to the [DAG section] in the nvf manual
 to find out more about the DAG system.
 :::
-
 <!-- deno-fmt-ignore-end -->

docs/manual/configuring/custom-plugins/lazy-method.md

@@ -1,7 +1,8 @@
 # Lazy Method {#sec-lazy-method}
 
-As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via
-`lz.n` and `lzn-auto-require`.
+As of version **0.7**, an API is exposed to allow configuring lazy-loaded
+plugins via `lz.n` and `lzn-auto-require`. Below is a comprehensive example of
+how it may be loaded to lazy-load an arbitrary plugin.
 
 ```nix
 {
@@ -41,7 +42,8 @@ As of version **0.7**, we exposed an API for configuring lazy-loaded plugins via
 
 ## LazyFile event {#sec-lazyfile-event}
 
-You can use the `LazyFile` user event to load a plugin when a file is opened:
+**nvf** re-implements `LazyFile` as a familiar user event to load a plugin when
+a file is opened:
 
 ```nix
 {
@@ -55,5 +57,6 @@ You can use the `LazyFile` user event to load a plugin when a file is opened:
 }
 ```
 
-You can consider `LazyFile` as an alias to
-`["BufReadPost" "BufNewFile" "BufWritePre"]`
+You can consider the `LazyFile` event as an alias to the combination of
+`"BufReadPost"`, `"BufNewFile"` and `"BufWritePre"`, i.e., a list containing all
+three of those events: `["BufReadPost" "BufNewFile" "BufWritePre"]`

docs/manual/configuring/custom-plugins/legacy-method.md

@@ -1,26 +1,31 @@
 # Legacy Method {#sec-legacy-method}
 
-Prior to version v0.5, the method of adding new plugins was adding the plugin
-package to `vim.startPlugins` and add its configuration as a DAG under one of
-`vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or
-prefer a more hands-on approach may use the old method where the load order of
-the plugins is determined by DAGs.
+Prior to version **0.5**, the method of adding new plugins was adding the plugin
+package to [](#opt-vim.startPlugins) and adding its configuration as a DAG under
+one of `vim.configRC` or [](#opt-vim.luaConfigRC). While `configRC` has been
+deprecated, users who have not yet updated to 0.5 or those who prefer a more
+hands-on approach may choose to use the old method where the load order of the
+plugins is explicitly determined by DAGs without internal abstractions.
 
-## Adding plugins {#sec-adding-plugins}
+## Adding New Plugins {#sec-adding-new-plugins}
 
-To add a plugin not available in nvf as a module to your configuration, you may
-add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at
-runtime.
+To add a plugin not available in **nvf** as a module to your configuration using
+the legacy method, you must add it to [](#opt-vim.startPlugins) in order to make
+it available to Neovim at runtime.
 
 ```nix
 {pkgs, ...}: {
   # Add a Neovim plugin from Nixpkgs to the runtime.
+  # This does not need to come explicitly from packages. 'vim.startPlugins'
+  # takes a list of *string* (to load internal plugins) or *package* to load
+  # a Neovim package from any source.
   vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
 }
 ```
 
-And to configure the added plugin, you can use the `luaConfigRC` option to
-provide configuration as a DAG using the **nvf** extended library.
+Once the package is available in Neovim's runtime, you may use the `luaConfigRC`
+option to provide configuration as a DAG using the **nvf** extended library in
+order to configure the added plugin,
 
 ```nix
 {inputs, ...}: let
@@ -29,6 +34,8 @@ provide configuration as a DAG using the **nvf** extended library.
   # to specialArgs, the 'inputs' prefix may be omitted.
   inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
 in {
+  # luaConfigRC takes Lua configuration verbatim and inserts it at an arbitrary
+  # position by default or if 'entryAnywhere' is used.
   vim.luaConfigRC.aerial-nvim= entryAnywhere ''
     require('aerial').setup {
       -- your configuration here

docs/manual/configuring/custom-plugins/non-lazy-method.md

@@ -1,8 +1,9 @@
 # Non-lazy Method {#sec-non-lazy-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:
+As of version **0.5**, we have a more extensive API for configuring plugins that
+should be preferred over the legacy method. This API is available as
+[](#opt-vim.extraPlugins). Instead of using DAGs exposed by the library
+_directly_, you may use the extra plugin module as follows:
 
 ```nix
 {pkgs, ...}: {
@@ -24,3 +25,5 @@ use the extra plugin module as follows:
   };
 }
 ```
+
+This provides a level of abstraction over the DAG system for faster iteration.