Merge pull request #10563 from hercules-ci/doc-glossary-base-directory

doc/glossary: Add base directory

doc/manual/src/glossary.md

@@ -295,6 +295,25 @@
   [path]: ./language/values.md#type-path
   [attribute name]: ./language/values.md#attribute-set
 
+- [base directory]{#gloss-base-directory}
+
+  The location from which relative paths are resolved.
+
+  - For expressions in a file, the base directory is the directory containing that file.
+    This is analogous to the directory of a [base URL](https://datatracker.ietf.org/doc/html/rfc1808#section-3.3).
+    <!-- which is sufficient for resolving non-empty URLs -->
+
+  <!--
+    The wording here may look awkward, but it's for these reasons:
+      * "with --expr": it's a flag, and not an option with an accompanying value
+      * "written in": the expression itself must be written as an argument,
+        whereas the more natural "passed as an argument" allows an interpretation
+        where the expression could be passed by file name.
+    -->
+  - For expressions written in command line arguments with [`--expr`](@docroot@/command-ref/opt-common.html#opt-expr), the base directory is the current working directory.
+
+  [base directory]: #gloss-base-directory
+
 - [experimental feature]{#gloss-experimental-feature}
 
   Not yet stabilized functionality guarded by named experimental feature flags.

doc/manual/src/language/values.md

@@ -97,8 +97,8 @@
   is not a path: it's parsed as an expression that selects the
   attribute `sh` from the variable `builder`. If the file name is
   relative, i.e., if it does not begin with a slash, it is made
-  absolute at parse time relative to the directory of the Nix
-  expression that contained it. For instance, if a Nix expression in
+  absolute at parse time relative to the [base directory](@docroot@/glossary.md#gloss-base-directory).
+  For instance, if a Nix expression in
   `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
   is `/foo/xyzzy/fnord.nix`.
 
@@ -107,7 +107,7 @@
   e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
   whose home directory is `/home/edolstra`.
 
-  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
+  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the base directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
 
   Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
   For example, assume you used a file path in an interpolated string during a `nix repl` session.