docs/manual: add more details to existing documentation pages

docs/default.nix

@@ -1,6 +1,6 @@
 {
   pkgs,
-  lib ? import ../lib/stdlib-extended.nix pkgs.lib,
+  lib,
   nmdSrc,
 }: let
   nmd = import nmdSrc {

docs/manual.xml

@@ -18,8 +18,8 @@
  <xi:include href="manual/try-it-out.xml"/>
  <xi:include href="manual/default-configs.xml"/>
  <xi:include href="manual/custom-configs.xml"/>
- <xi:include href="manual/custom-plugins.xml"/>
  <xi:include href="manual/custom-package.xml"/>
+ <xi:include href="manual/custom-plugins.xml"/>
  <xi:include href="manual/home-manager.xml"/>
  <xi:include href="manual/languages.xml"/>
  <xi:include href="manual/hacking.xml"/>

docs/manual/custom-configs.adoc

@@ -1,7 +1,8 @@
 [[ch-custom-configuration]]
 == Custom Configuration
 
-Custom configuration is done with the `neovimConfiguration` function. It takes in the configuration as a module. The output of the configuration function is an attrset.
+Custom configuration is done with the `neovimConfiguration` while using the flake as a standalone package.
+It takes in the configuration as a module. The output of the configuration function is an attrset.
 
 [source,nix]
 ----
@@ -40,8 +41,28 @@ The following is an example of a barebones vim configuration with the default th
       inherit pkgs;
     };
   in {
+    # this will make the package available as a flake input
     packages.${system}.neovim = customNeovim.neovim;
+
+    # this is an example nixosConfiguration using the built neovim package
+    nixosConfigurations = {
+      yourHostName = nixpkgs.lib.nixosSystem {
+        # ...
+        modules = [
+          ./configuration.nix # or whatever your configuration is
+
+          # this will make wrapped neovim available in your system packages
+          {environment.systemPackages = [customNeovim.neovim];}
+        ];
+        # ...
+      };
+    };
   };
 }
 ----
 
+Your built neovim configuration can be exposed as a flake output, or be added to your system packages to make
+it available across your system. You may also consider passing the flake output to home-manager to make it available
+to a specific user *without* using the home-manager module.
+
+

docs/manual/custom-plugins.adoc

@@ -4,7 +4,7 @@
 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.
 
-
+[[sec-new-method]]
 === New Method
 As of version 0.5, we have a more extensive API for configuring plugins, under `vim.extraPlugins`.
 
@@ -22,7 +22,7 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
         }
       '';
     };
-    
+
     harpoon = {
       package = harpoon;
       setup = "require('harpoon').setup {}";
@@ -32,8 +32,10 @@ Instead of using DAGs exposed by the library, you may use the extra plugin modul
 }
 ----
 
+[[sec-old-method]]
 === 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.
+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.
 
 [source,nix]
 ----
@@ -50,16 +52,23 @@ Users who have not yet updated to 0.5, or prefer a more hands-on approach may us
 }
 ----
 
-However, just making the plugin available might not be enough. In that case, you can write custom vimscript or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
+However, just making the plugin available might not be enough. In that case, you can write custom vimscript
+or lua config, using `config.vim.configRC` or `config.vim.luaConfigRC` respectively.
 These options are attribute sets, and you need to give the configuration you're adding some name, like this:
 
 [source,nix]
 ----
 {
+  # this will create an "aquarium" section in your init.vim with the contents of your custom config
+  # which will be *appended* to the rest of your configuration, inside your init.vim
   config.vim.configRC.aquarium = "colorscheme aquiarum";
 }
 ----
 
-Note: If your configuration needs to be put in a specific place in the config, you can use functions from `inputs.neovim-flake.lib.nvim.dag` to order it. Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix.
+Note: If your configuration needs to be put in a specific place in the config, you can use functions from
+`inputs.neovim-flake.lib.nvim.dag` to order it.
+Refer to https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix to find out more about
+the DAG system.
 
-Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue with your findings so that we can make it available for everyone easily.
+Also, if you successfully made your plugin work, please make a PR to add it to the flake, or open an issue
+with your findings so that we can make it available for everyone easily.

docs/manual/home-manager.adoc

@@ -1,7 +1,10 @@
 [[ch-hm-module]]
 == Home Manager
 
-The Home Manager module allows us to customize the different `vim` options. To use it, we first add the input flake.
+The Home Manager module allows us to customize the different `vim` options from inside the home-manager configuration
+and it is the preferred way of configuring neovim-flake, both on NixOS and non-NixOS systems.
+
+To use it, we first add the input flake.
 
 [source,nix]
 ----
@@ -10,20 +13,49 @@ The Home Manager module allows us to customize the different `vim` options. To u
     url = github:notashelf/neovim-flake;
     # you can override input nixpkgs
     inputs.nixpkgs.follows = "nixpkgs";
+    # you can also override individual plugins
+    # i.e inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- obsidian nvim needs to be in your inputs
   };
 }
 ----
 
-Followed by importing the HM module.
+Followed by importing the home-manager module somewhere in your configuration.
 
 [source,nix]
 ----
 {
-  imports = [ neovim-flake.homeManagerModules.default ];
+  # assuming neovim-flake is in your inputs and inputs is in the argset
+  imports = [ inputs.neovim-flake.homeManagerModules.default ];
 }
 ----
 
-Then we should be able to use the given module. E.g.
+An example installation for standalone home-manager would look like this:
+
+[source,nix]
+----
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    home-manager.url = "github:nix-community/home-manager";
+    stylix.url = "github:notashelf/neovim-flake";
+  };
+
+  outputs = { nixpkgs, home-manager, neovim-flake ... }: let
+  system = "x86_64-linux"; in {
+    # ↓ this is the home-manager output in the flake schema
+    homeConfigurations."yourUsername»" = home-manager.lib.homeManagerConfiguration {
+      pkgs = nixpkgs.legacyPackages.x86_64-linux;
+      modules = [
+        neovim-flake.homeManagerModules.default # <- this imports the home-manager module that provides the options
+        ./home.nix # your home-manager configuration, probably where you will want to add programs.neovim-flake options
+      ];
+    };
+  };
+}
+----
+
+Once the module is imported, we will be able to define the following options (and much more) from inside the
+home-manager configuration.
 
 [source,nix]
 ----
@@ -31,7 +63,8 @@ Then we should be able to use the given module. E.g.
   programs.neovim-flake = {
 
     enable = true;
-    # your settings need to go into the settings attrset
+    # your settings need to go into the settings attribute set
+    # most settings are documented in the appendix
     settings = {
       vim.viAlias = false;
       vim.vimAlias = true;
@@ -43,4 +76,10 @@ Then we should be able to use the given module. E.g.
 }
 ----
 
+[NOTE]
+====
+You may find all avaliable options in the https://notashelf.github.io/neovim-flake/options[appendix]
+====
+
+
 

docs/manual/languages.adoc

@@ -15,21 +15,25 @@ Language specific support means there is a combination of language specific plug
 * SQL: <<opt-vim.languages.sql.enable>>
 * Dart: <<opt-vim.languages.dart.enable>>
 * Go: <<opt-vim.languages.go.enable>>
+* Lua: <<opt-vim.languages.lua.enable>>
 
-Adding support for more languages, and improving support for existing ones are great places where you can contribute with a PR.
+Adding support for more languages, and improving support for existing ones are great places
+where you can contribute with a PR.
 
 === LSP Custom Packages/Command
 
-In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide the command to launch the language server, as a list of strings.
+In any of the `opt.languages.<language>.lsp.package` options you can provide your own LSP package, or provide
+the command to launch the language server, as a list of strings.
 
-You can use this to skip automatic installation of a language server, and instead use the one found in your `$PATH` during runtime, for example:
+You can use this to skip automatic installation of a language server, and instead
+use the one found in your `$PATH` during runtime, for example:
 
 [source,nix]
 ----
 vim.languages.java = {
-	lsp = {
+  lsp = {
-		enable = true;
+    enable = true;
-		package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
+	package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
-	};
+  };
 }
 ----

docs/manual/try-it-out.adoc

@@ -1,34 +1,53 @@
 [[ch-try-it-out]]
 == Try it out
 
+Thanks to the portability of Nix, you can try out neovim-flake without actually installing it to your machine.
+Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, three
+configurations are provided:
+
+* Nix
+* Tidal
+* Maximal
+
+You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
+
 [source,console]
 ----
 $ cachix use neovim-flake # Optional: it'll save you CPU resources and time
-$ nix run github:notashelf/neovim-flake # will run the default configuration
+$ nix run github:notashelf/neovim-flake#nix # will run the default minimal configuration
 ----
 
+Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
+once you garbage collect. If you wish to install neovim-flake, please take a look at
+<<ch-custom-configuration,custom-configuration>> or <<ch-hm-module,home-manager>> sections for installation
+instructions.
 
-=== Nix
+[[sec-using-prebuild-configs]]
-
-By default LSP support for Nix is enabled alongside all complementary Neovim plugins. By running `nix run .`, which is the default package,
-you will build Neovim with this config.
-
-=== Tidal
-
-Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
-
-=== Maximal
-
-Maximal is the ultimate configuration that will enable basically everything. Keep in mind, however, that this will pull a lot of dependencies.
-
-You are strongly recommended to use the binary cache if you would like to try the Maximal configuration.
-
-
 === Using Prebuilt Configs
 
 [source,console]
 ----
-$ nix run github:notashelf/neovim-flake#nix 
+$ nix run github:notashelf/neovim-flake#nix
 $ nix run github:notashelf/neovim-flake#tidal
 $ nix run github:notashelf/neovim-flake#maximal
 ----
+
+
+[[sec-available-configs]]
+=== Available Configs
+
+==== Nix
+
+`Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
+By running `nix run .`, which is the default package, you will build Neovim with this config.
+
+==== Tidal
+
+Tidal is an alternative config that adds vim-tidal on top of the plugins from the Nix configuration.
+
+==== Maximal
+
+`Maximal` is the ultimate configuration that will enable support for more commonly used language as well as additional
+complementary plugins. Keep in mind, however, that this will pull a lot of dependencies.
+
+You are *strongly* recommended to use the binary cache if you would like to try the Maximal configuration.