Tune documentation

README.md

@@ -18,12 +18,11 @@ Specifically, this project helps
 
 This source's [doc directory](doc) provides a variety of documents to not only help you use this project, but to also get an introduction to the Nix ecosystem.
 
-Among other benefits, Nix gives use an incredible amount of control and repeatability of our software projects. If you don't know much about Nix, consider reading the following:
+Among other benefits, Nix gives use an incredible amount of control and repeatability of our software projects. If you don't know much about Nix, consider reading the following provided guides:
 
 -   [Introduction to Nix and motivations to use it](doc/nix-introduction.md)
 -   [Nix installation and configuration guide](doc/nix-installation.md)
--   [Nix end user guide with flakes](doc/nix-usage-flakes.md)
--   [Nix end user guide without flakes](doc/nix-usage-noflakes.md)
+-   [Nix end user guide](doc/nix-usage-flakes.md)
 -   [Introduction to the Nix programming language](doc/nix-language.md)
 
 If you know something about Nix, then these documents will help you get started using this project:

README.org

@@ -20,12 +20,11 @@ use this project, but to also get an introduction to the Nix ecosystem.
 
 Among other benefits, Nix gives use an incredible amount of control and
 repeatability of our software projects. If you don't know much about Nix,
-consider reading the following:
+consider reading the following provided guides:
 
 - [[file:doc/nix-introduction.org][Introduction to Nix and motivations to use it]]
 - [[file:doc/nix-installation.org][Nix installation and configuration guide]]
-- [[file:doc/nix-usage-flakes.org][Nix end user guide with flakes]]
-- [[file:doc/nix-usage-noflakes.org][Nix end user guide without flakes]]
+- [[file:doc/nix-usage-flakes.org][Nix end user guide]]
 - [[file:doc/nix-language.org][Introduction to the Nix programming language]]
 
 If you know something about Nix, then these documents will help you get started

doc/internal/links.org

@@ -3,20 +3,18 @@
 #+link: fhs https://www.pathname.com/fhs/
 #+link: gfm https://github.github.com/gfm/
 #+link: github-actions https://github.com/shajra/nix-project/actions
-#+link: github-token https://github.com/settings/tokens
 #+link: litprog https://en.wikipedia.org/wiki/Literate_programming
 #+link: nix https://nixos.org/nix
 #+link: nix-flake https://nixos.wiki/wiki/Flakes
+#+link: nix-flake-compat https://github.com/edolstra/flake-compat
+#+link: nix-flake-inputs https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references
+#+link: nix-flake-outputs https://nixos.wiki/wiki/Flakes#Output_schema
 #+link: nix-flake-parts https://github.com/hercules-ci/flake-parts
 #+link: nix-flake-parts-doc https://flake.parts
 #+link: nix-flake-parts-doc-options https://flake.parts/options/flake-parts.html
 #+link: nix-flake-parts-doc-modargs https://flake.parts/module-arguments.html
-#+link: nix-flake-compat https://github.com/edolstra/flake-compat
-#+link: nix-flake-inputs https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references
-#+link: nix-flake-outputs https://nixos.wiki/wiki/Flakes#Output_schema
-#+link: nix-install-quick https://nixos.org/download.html#download-nix
 #+link: nix-install-manual https://nixos.org/manual/nix/stable/installation/installation.html
-#+link: nix-uninstall https://nixos.org/manual/nix/stable/installation/installing-binary.html#uninstalling
+#+link: nix-install-quick https://nixos.org/download.html#download-nix
 #+link: nix-language-manual https://nixos.org/manual/nix/stable/language/index.html
 #+link: nix-language-tutorial https://nixos.org/guides/nix-language.html
 #+link: nix-learn https://nixos.org/learn.html
@@ -26,6 +24,7 @@
 #+link: nixpkgs https://github.com/NixOS/nixpkgs
 #+link: nixpkgs-manual https://nixos.org/nixpkgs/manual
 #+link: nixpkgs-manual-langs https://nixos.org/manual/nixpkgs/stable/#chap-language-support
+#+link: nix-uninstall https://nixos.org/manual/nix/stable/installation/installing-binary.html#uninstalling
 #+link: org https://www.gnu.org/software/emacs/manual/html_node/emacs/Org-Mode.html
 #+link: org-blocks-src https://orgmode.org/manual/Working-with-Source-Code.html#Working-with-Source-Code
 #+link: org-blocks-src-eval https://orgmode.org/manual/Evaluating-Code-Blocks.html#Evaluating-Code-Blocks

doc/nix-installation.md

@@ -84,7 +84,11 @@ The provided [introduction to Nix](nix-introduction.md) covers in detail what th
 
 As you can guess, the `flakes` feature enables flakes functionality in Nix. The `nix-command` feature enables a variety of subcommands of Nix's newer `nix` command-line tool, some of which allow us to work with flakes.
 
-There is a way to use flakes local to just a single command-line invocation by using `nix --extra-experimental-features 'nix-command flakes' …`, so users avoiding using flakes can try out using flakes with little commitment. For those users, this can be useful to set to a shell alias.
+There is a way to use flakes local to just a single command-line invocation by using `nix --extra-experimental-features 'nix-command flakes' …`, so users can try out using flakes without enabling it globally. For those users, this can be useful to set to a shell alias. Here's an example that works in most POSIX-compliant shells:
+
+```sh
+alias nix-flakes = nix --extra-experimental-features 'nix-command flakes'
+```
 
 As discussed in the introduction, `nix-command` is actually enabled by default. You don't need to enable it explicitly (though you could disable it).
 

doc/nix-installation.org

@@ -139,9 +139,14 @@ As you can guess, the =flakes= feature enables flakes functionality in Nix. The
 command-line tool, some of which allow us to work with flakes.
 
 There is a way to use flakes local to just a single command-line invocation by
-using ~nix --extra-experimental-features 'nix-command flakes' …~, so users
-avoiding using flakes can try out using flakes with little commitment. For those
-users, this can be useful to set to a shell alias.
+using ~nix --extra-experimental-features 'nix-command flakes' …~, so users can
+try out using flakes without enabling it globally. For those users, this can be
+useful to set to a shell alias. Here's an example that works in most
+POSIX-compliant shells:
+
+#+begin_src sh :eval no
+alias nix-flakes = nix --extra-experimental-features 'nix-command flakes'
+#+end_src
 
 As discussed in the introduction, =nix-command= is actually enabled by default.
 You don't need to enable it explicitly (though you could disable it).