From f67eb111acf66cc3ad0e3da0b57b115e668f6e2b Mon Sep 17 00:00:00 2001
From: Aaron Janse <aaron@ajanse.me>
Date: Wed, 13 Mar 2019 18:40:00 -0700
Subject: [PATCH 1/2] nixos/manual: clarify declarative packages section

---
 .../manual/configuration/declarative-packages.xml   | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index be9884fe9dce..bf7430244545 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/nixos/doc/manual/configuration/declarative-packages.xml
@@ -14,9 +14,10 @@
 <programlisting>
 <xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
 </programlisting>
-  The effect of this specification is that the Thunderbird package from Nixpkgs
-  will be built or downloaded as part of the system when you run
-  <command>nixos-rebuild switch</command>.
+  The <literal>pkgs</literal> variable is used to reference packages in your
+  root channel. The effect of this specification is that the Thunderbird
+  package from your root Nixpkgs channel will be built or downloaded as part of
+  the system when you run <command>nixos-rebuild switch</command>.
  </para>
 
  <para>
@@ -27,8 +28,10 @@ nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
 <replaceable>...</replaceable>
 </screen>
   The first column in the output is the <emphasis>attribute name</emphasis>,
-  such as <literal>nixos.thunderbird</literal>. (The <literal>nixos</literal>
-  prefix allows distinguishing between different channels that you might have.)
+  such as <literal>nixos.thunderbird</literal>. The <literal>nixos</literal>
+  prefix tells us that we want to get the package from the `nixos` channel.
+  Some systems have other channels installed, such as `nixpkgs` or custom
+  channels for development purposes.
  </para>
 
  <para>

From 0258cff88787ac33121b7e36fef6eebde638f4da Mon Sep 17 00:00:00 2001
From: Aaron Janse <aaron@ajanse.me>
Date: Thu, 14 Mar 2019 19:08:38 -0700
Subject: [PATCH 2/2] nixos/manual: reword note in declarative packages section

---
 .../configuration/declarative-packages.xml     | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml
index bf7430244545..c9acbefea60e 100644
--- a/nixos/doc/manual/configuration/declarative-packages.xml
+++ b/nixos/doc/manual/configuration/declarative-packages.xml
@@ -14,10 +14,9 @@
 <programlisting>
 <xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
 </programlisting>
-  The <literal>pkgs</literal> variable is used to reference packages in your
-  root channel. The effect of this specification is that the Thunderbird
-  package from your root Nixpkgs channel will be built or downloaded as part of
-  the system when you run <command>nixos-rebuild switch</command>.
+  The effect of this specification is that the Thunderbird package from Nixpkgs
+  will be built or downloaded as part of the system when you run
+  <command>nixos-rebuild switch</command>.
  </para>
 
  <para>
@@ -28,10 +27,13 @@ nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
 <replaceable>...</replaceable>
 </screen>
   The first column in the output is the <emphasis>attribute name</emphasis>,
-  such as <literal>nixos.thunderbird</literal>. The <literal>nixos</literal>
-  prefix tells us that we want to get the package from the `nixos` channel.
-  Some systems have other channels installed, such as `nixpkgs` or custom
-  channels for development purposes.
+  such as <literal>nixos.thunderbird</literal>.
+ </para>
+ <para>
+  Note: the <literal>nixos</literal> prefix tells us that we want to get the
+  package from the <literal>nixos</literal> channel and works only in CLI tools.
+
+  In declarative configuration use <literal>pkgs</literal> prefix (variable).
  </para>
 
  <para>