From 915a93321a41a4e3d41ee5fe4eff78ef1c530fc4 Mon Sep 17 00:00:00 2001
From: Gabriel Arazas <foo.dogsquared@gmail.com>
Date: Mon, 19 Sep 2022 10:56:06 +0800
Subject: [PATCH] docs: update

---
 hosts/README.adoc | 20 +++++++++++++++++++-
 pkgs/README.adoc  |  5 ++++-
 users/README.adoc | 13 ++++++++++---
 3 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/hosts/README.adoc b/hosts/README.adoc
index 3db312e6..11b96ee8 100644
--- a/hosts/README.adoc
+++ b/hosts/README.adoc
@@ -26,12 +26,30 @@ For managing users, there are multiple ways to manage them with this config:
 
 * If you intend to import users from the link:../users/nixos/[`../users/nixos/`], you can simply import them through `imports` in the system module.
 +
+--
 For a convenient option, there is the function `getUsers` defined from the link:../lib/private.nix[private custom library].
 You can use it as follows:
-+
+
 [source, nix]
 ----
 imports = [ # Your modules ]
     # Import the following NixOS users.
     ++ (lib.attrValues (lib.getUsers "nixos" [ "foo-dogsquared" "polski" ]));
 ----
+--
+
+* You could also easily map link:../users/home-manager[one of my home-manager configurations] into one of the users for a NixOS system with `lib.mapHomeManagerUser` which accepts two arguments: a name from of the home-manager user folder and the user config as if configuration with `users.users.<name>`.
++
+--
+Here's an example to easily get my main home-manager config to be one of the users of the system.
+
+[source, nix]
+----
+lib.mapHomeManagerUser "foo-dogsquared" {
+  extraGroups = [ "audio" "docker" ];
+  password = "what";
+  createHome = true;
+  home = "/home/foo-dogsquared";
+}
+----
+--
diff --git a/pkgs/README.adoc b/pkgs/README.adoc
index 774ffb54..d19355fe 100644
--- a/pkgs/README.adoc
+++ b/pkgs/README.adoc
@@ -5,9 +5,12 @@ My custom packages live here.
 It is setup similar to link:https://github.com/NixOS/nixpkgs/[nixpkgs] and link:https://github.com/foo-dogsquared/nur[my previous NUR].
 Thus, the conventions are similar to the package definitions in the mentioned repositories.
 
+It should be composed of a single entry point describing the entirety of the package repository similar to the link:https://github.com/NixOS/nixpkgs/blob/767542707d394ff15ac1981e903e005ba69528b5/pkgs/top-level/all-packages.nix[`pkgs/top-level/all-packages.nix` for nixpkgs].
+This is to easily import the package repository in a neat way.
+
 To build the packages...
 
 * With Nix pre-v2.3, `nix-build ./pkgs -A ${pkg}`.
 
-* Nix v2.4 and enabled Nix flakes experimental feature and new CLi (e.g., `experimental-features = nix-command flakes`), `nix build .#${pkg}`.
+* Nix v2.4 and enabled Nix flakes experimental feature and new CLi (e.g., `experimental-features = nix-command flakes`), `nix build --file ./pkgs`.
 
diff --git a/users/README.adoc b/users/README.adoc
index d8a0adbf..a020b7bf 100644
--- a/users/README.adoc
+++ b/users/README.adoc
@@ -2,7 +2,13 @@
 :toc:
 
 This is where user-specific configurations comes in.
-Similar to modules, the top-level of this directory contains users for various modules (e.g., home-manager, NixOS).
+Similar to modules, the top-level of this directory contains users for various config types (e.g., home-manager, NixOS).
+
+As such, files put in here are only a part of the total sum of configuration (whether it is a home-manager configuration or a NixOS system).
+It shouldn't fully configure their respective system and should be put as a host configuration otherwise.
+
+Users shouldn't also have their own set of modules similar to this project's own modules.
+They should be imported as a profile or hardcoded in the user config.
 
 Take note of the following structure:
 
@@ -20,11 +26,12 @@ users/
 └── README.adoc
 ----
 
-It doesn't require to have users to be present for all types.
+This folder is to be expected to be imported through `lib.filesToAttr` from the link:../lib/default.nix[`../lib/default.nix`].
+
 There are conventions for setting in each user type.
 
 * For NixOS user configuration, it is expect to only have one user with their respective user-specific configuration.
-This includes user-specific packages, home-manager-specific configuration (even importing them from `./home-manager` users), and so forth.
+This includes user-specific packages, home-manager-specific configuration footnote:[Though, it is encouraged to put it as a separate home-manager user configuration if it's big enough.], and so forth.
 If you want to set users from the host, see link:../hosts/README.adoc[Host-specific configurations] for more details.
 
 * home-manager users are just home-manager configurations (i.e., `$XDG_CONFIG_HOME/nix/home.nix`).