modules/mkRemovedOptionModule: add replacement doc

When displaying a warning about a removed Option we should always
include reasoning why it was removed and how to get the same
functionality without it.

Introduces such a description argument and patches occurences (mostly
with an empty string).

startGnuPGAgent: further notes on replacement

1 files changed, 35 insertions, 0 deletions

diff --git a/nixos/doc/manual/release-notes/rl-1603.xml b/nixos/doc/manual/release-notes/rl-1603.xml
index c51316bd2808..f460e00e836e 100644
--- a/nixos/doc/manual/release-notes/rl-1603.xml
+++ b/nixos/doc/manual/release-notes/rl-1603.xml
@@ -385,6 +385,41 @@ services.syncthing = {
       the github issue</link>.
     </para>
   </listitem>
+
+  <listitem>
+    <para>
+      The <literal>services.xserver.startGnuPGAgent</literal> option has been removed.
+      GnuPG 2.1.x changed the way the gpg-agent works, and that new approach no
+      longer requires (or even supports) the "start everything as a child of the
+      agent" scheme we've implemented in NixOS for older versions.
+      To configure the gpg-agent for your X session, add the following code to
+      <filename>~/.bashrc</filename> or some file that’s sourced when your shell is started:
+    <programlisting>
+GPG_TTY=$(tty)
+export GPG_TTY
+    </programlisting>
+      If you want to use gpg-agent for SSH, too, add the following to your session
+      initialization (e.g. <literal>displayManager.sessionCommands</literal>)
+    <programlisting>
+gpg-connect-agent /bye
+unset SSH_AGENT_PID
+export SSH_AUTH_SOCK="''${HOME}/.gnupg/S.gpg-agent.ssh"
+    </programlisting>
+      and make sure that
+    <programlisting>
+enable-ssh-support
+    </programlisting>
+      is included in your <filename>~/.gnupg/gpg-agent.conf</filename>.
+      You will need to use <command>ssh-add</command> to re-add your ssh keys.
+      If gpg’s automatic transformation of the private keys to the new format fails,
+      you will need to re-import your private keyring as well:
+    <programlisting>
+gpg --import ~/.gnupg/secring.gpg
+    </programlisting>
+    The <command>gpg-agent(1)</command> man page has more details about this subject,
+    i.e. in the "EXAMPLES" section.
+    </para>
+  </listitem>
 </itemizedlist>