From abdf8c99ff47f06ff4449a57b3d99b940191d757 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 29 Nov 2025 12:02:24 +0100
Subject: [PATCH] Document attribute escaping

---
 extras/bundlers.nix        |  7 +++++++
 modules/apps.nix           | 11 ++++++++++-
 modules/devShells.nix      |  8 ++++++++
 modules/legacyPackages.nix | 10 ++++++++++
 modules/packages.nix       | 11 +++++++++++
 5 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/extras/bundlers.nix b/extras/bundlers.nix
index e83bb5f..54ee22c 100644
--- a/extras/bundlers.nix
+++ b/extras/bundlers.nix
@@ -29,6 +29,13 @@ mkTransposedPerSystemModule {
       `nix bundle --bundler .#<name> .#<package>` bundles `<package>` using bundler `<name>`.
 
       Define a `default` bundler to use `nix bundle --bundler .#`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix bundle --bundler '.#"example.com"' .#package
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./bundlers.nix;
diff --git a/modules/apps.nix b/modules/apps.nix
index 2f30a77..8171048 100644
--- a/modules/apps.nix
+++ b/modules/apps.nix
@@ -54,7 +54,16 @@ mkTransposedPerSystemModule {
     type = types.lazyAttrsOf appType;
     default = { };
     description = ''
-      Programs runnable with nix run `<name>`.
+      An attribute set of programs runnable with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run.html).
+
+      `nix run .#<name>` will run `apps.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix run '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = lib.literalExpression or lib.literalExample ''
       {
diff --git a/modules/devShells.nix b/modules/devShells.nix
index c0cc6c5..522d187 100644
--- a/modules/devShells.nix
+++ b/modules/devShells.nix
@@ -16,7 +16,15 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of packages to be used as shells.
+
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix develop '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
     example = literalExpression ''
       {
diff --git a/modules/legacyPackages.nix b/modules/legacyPackages.nix
index fb17e14..bf7a721 100644
--- a/modules/legacyPackages.nix
+++ b/modules/legacyPackages.nix
@@ -15,6 +15,16 @@ mkTransposedPerSystemModule {
     default = { };
     description = ''
       An attribute set of unmergeable values. This is also used by [`nix build .#<attrpath>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
+
+      `legacyPackages` supports nested attribute sets. Use `.` to access nested attributes:
+      `.#foo.bar` refers to the `bar` attribute in `foo`.
+
+      Attribute names that literally contain special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./legacyPackages.nix;
diff --git a/modules/packages.nix b/modules/packages.nix
index 20f0071..797727f 100644
--- a/modules/packages.nix
+++ b/modules/packages.nix
@@ -17,6 +17,17 @@ mkTransposedPerSystemModule {
       An attribute set of packages to be built by [`nix build`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html).
 
       `nix build .#<name>` will build `packages.<name>`.
+
+      You can also build attributes of a package using `.` to access nested attributes:
+      `.#foo.tests.simple` builds the `simple` attribute in `foo.tests`.
+      This is a Nixpkgs convention (packages having "passthru" attributes like `tests`) which gets no special treatment in Flakes.
+
+      Attribute names containing special characters like `.` must be doubly quoted when used in installable arguments:
+      ```bash
+      nix build '.#"example.com"'
+      ```
+
+      Consider using `:` or `/` as separators instead (e.g., `foo:bar`) for better command-line usability.
     '';
   };
   file = ./packages.nix;