[RFC] manual: rename to users and contributors manual, add some user notes … (#60682)

* manual: rename to users and contributors manual, add some user notes that should be there but don't fit in any chapter
* manual: move the package notes that are completely usage-related to the upper user notes section
* manual: link to package-specific development notes from user notes

1 files changed, 0 insertions, 391 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index 54f3079d5541..d3cffab33076 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -352,312 +352,6 @@ packageOverrides = pkgs: {
 </screen>
   </para>
  </section>
- <section xml:id="sec-steam">
-  <title>Steam</title>
-
-  <section xml:id="sec-steam-nix">
-   <title>Steam in Nix</title>
-
-   <para>
-    Steam is distributed as a <filename>.deb</filename> file, for now only as
-    an i686 package (the amd64 package only has documentation). When unpacked,
-    it has a script called <filename>steam</filename> that in ubuntu (their
-    target distro) would go to <filename>/usr/bin </filename>. When run for the
-    first time, this script copies some files to the user's home, which include
-    another script that is the ultimate responsible for launching the steam
-    binary, which is also in $HOME.
-   </para>
-
-   <para>
-    Nix problems and constraints:
-    <itemizedlist>
-     <listitem>
-      <para>
-       We don't have <filename>/bin/bash</filename> and many scripts point
-       there. Similarly for <filename>/usr/bin/python</filename> .
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       We don't have the dynamic loader in <filename>/lib </filename>.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       The <filename>steam.sh</filename> script in $HOME can not be patched, as
-       it is checked and rewritten by steam.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       The steam binary cannot be patched, it's also checked.
-      </para>
-     </listitem>
-    </itemizedlist>
-   </para>
-
-   <para>
-    The current approach to deploy Steam in NixOS is composing a FHS-compatible
-    chroot environment, as documented
-    <link xlink:href="http://sandervanderburg.blogspot.nl/2013/09/composing-fhs-compatible-chroot.html">here</link>.
-    This allows us to have binaries in the expected paths without disrupting
-    the system, and to avoid patching them to work in a non FHS environment.
-   </para>
-  </section>
-
-  <section xml:id="sec-steam-play">
-   <title>How to play</title>
-
-   <para>
-    For 64-bit systems it's important to have
-<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting>
-    in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need
-<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting>
-    if you are using PulseAudio - this will enable 32bit ALSA apps integration.
-    To use the Steam controller or other Steam supported controllers such as
-    the DualShock 4 or Nintendo Switch Pro, you need to add
-<programlisting>hardware.steam-hardware.enable = true;</programlisting>
-    to your configuration.
-   </para>
-  </section>
-
-  <section xml:id="sec-steam-troub">
-   <title>Troubleshooting</title>
-
-   <para>
-    <variablelist>
-     <varlistentry>
-      <term>
-       Steam fails to start. What do I do?
-      </term>
-      <listitem>
-       <para>
-        Try to run
-<programlisting>strace steam</programlisting>
-        to see what is causing steam to fail.
-       </para>
-      </listitem>
-     </varlistentry>
-     <varlistentry>
-      <term>
-       Using the FOSS Radeon or nouveau (nvidia) drivers
-      </term>
-      <listitem>
-       <itemizedlist>
-        <listitem>
-         <para>
-          The <literal>newStdcpp</literal> parameter was removed since NixOS
-          17.09 and should not be needed anymore.
-         </para>
-        </listitem>
-        <listitem>
-         <para>
-          Steam ships statically linked with a version of libcrypto that
-          conflics with the one dynamically loaded by radeonsi_dri.so. If you
-          get the error
-<programlisting>steam.sh: line 713: 7842 Segmentation fault (core dumped)</programlisting>
-          have a look at
-          <link xlink:href="https://github.com/NixOS/nixpkgs/pull/20269">this
-          pull request</link>.
-         </para>
-        </listitem>
-       </itemizedlist>
-      </listitem>
-     </varlistentry>
-     <varlistentry>
-      <term>
-       Java
-      </term>
-      <listitem>
-       <orderedlist>
-        <listitem>
-         <para>
-          There is no java in steam chrootenv by default. If you get a message
-          like
-<programlisting>/home/foo/.local/share/Steam/SteamApps/common/towns/towns.sh: line 1: java: command not found</programlisting>
-          You need to add
-<programlisting> steam.override { withJava = true; };</programlisting>
-          to your configuration.
-         </para>
-        </listitem>
-       </orderedlist>
-      </listitem>
-     </varlistentry>
-    </variablelist>
-   </para>
-  </section>
-
-  <section xml:id="sec-steam-run">
-   <title>steam-run</title>
-
-   <para>
-    The FHS-compatible chroot used for steam can also be used to run other
-    linux games that expect a FHS environment. To do it, add
-<programlisting>pkgs.(steam.override {
-          nativeOnly = true;
-          newStdcpp = true;
-        }).run</programlisting>
-    to your configuration, rebuild, and run the game with
-<programlisting>steam-run ./foo</programlisting>
-   </para>
-  </section>
- </section>
- <section xml:id="sec-emacs">
-  <title>Emacs</title>
-
-  <section xml:id="sec-emacs-config">
-   <title>Configuring Emacs</title>
-
-   <para>
-    The Emacs package comes with some extra helpers to make it easier to
-    configure. <varname>emacsWithPackages</varname> allows you to manage
-    packages from ELPA. This means that you will not have to install that
-    packages from within Emacs. For instance, if you wanted to use
-    <literal>company</literal>, <literal>counsel</literal>,
-    <literal>flycheck</literal>, <literal>ivy</literal>,
-    <literal>magit</literal>, <literal>projectile</literal>, and
-    <literal>use-package</literal> you could use this as a
-    <filename>~/.config/nixpkgs/config.nix</filename> override:
-   </para>
-
-<screen>
-{
-  packageOverrides = pkgs: with pkgs; {
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
-      company
-      counsel
-      flycheck
-      ivy
-      magit
-      projectile
-      use-package
-    ]));
-  }
-}
-</screen>
-
-   <para>
-    You can install it like any other packages via <command>nix-env -iA
-    myEmacs</command>. However, this will only install those packages. It will
-    not <literal>configure</literal> them for us. To do this, we need to
-    provide a configuration file. Luckily, it is possible to do this from
-    within Nix! By modifying the above example, we can make Emacs load a custom
-    config file. The key is to create a package that provide a
-    <filename>default.el</filename> file in
-    <filename>/share/emacs/site-start/</filename>. Emacs knows to load this
-    file automatically when it starts.
-   </para>
-
-<screen>
-{
-  packageOverrides = pkgs: with pkgs; rec {
-    myEmacsConfig = writeText "default.el" ''
-;; initialize package
-
-(require 'package)
-(package-initialize 'noactivate)
-(eval-when-compile
-  (require 'use-package))
-
-;; load some packages
-
-(use-package company
-  :bind ("&lt;C-tab&gt;" . company-complete)
-  :diminish company-mode
-  :commands (company-mode global-company-mode)
-  :defer 1
-  :config
-  (global-company-mode))
-
-(use-package counsel
-  :commands (counsel-descbinds)
-  :bind (([remap execute-extended-command] . counsel-M-x)
-         ("C-x C-f" . counsel-find-file)
-         ("C-c g" . counsel-git)
-         ("C-c j" . counsel-git-grep)
-         ("C-c k" . counsel-ag)
-         ("C-x l" . counsel-locate)
-         ("M-y" . counsel-yank-pop)))
-
-(use-package flycheck
-  :defer 2
-  :config (global-flycheck-mode))
-
-(use-package ivy
-  :defer 1
-  :bind (("C-c C-r" . ivy-resume)
-         ("C-x C-b" . ivy-switch-buffer)
-         :map ivy-minibuffer-map
-         ("C-j" . ivy-call))
-  :diminish ivy-mode
-  :commands ivy-mode
-  :config
-  (ivy-mode 1))
-
-(use-package magit
-  :defer
-  :if (executable-find "git")
-  :bind (("C-x g" . magit-status)
-         ("C-x G" . magit-dispatch-popup))
-  :init
-  (setq magit-completing-read-function 'ivy-completing-read))
-
-(use-package projectile
-  :commands projectile-mode
-  :bind-keymap ("C-c p" . projectile-command-map)
-  :defer 5
-  :config
-  (projectile-global-mode))
-    '';
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
-      (runCommand "default.el" {} ''
-mkdir -p $out/share/emacs/site-lisp
-cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
-'')
-      company
-      counsel
-      flycheck
-      ivy
-      magit
-      projectile
-      use-package
-    ]));
-  };
-}
-</screen>
-
-   <para>
-    This provides a fairly full Emacs start file. It will load in addition to
-    the user's presonal config. You can always disable it by passing
-    <command>-q</command> to the Emacs command.
-   </para>
-
-   <para>
-    Sometimes <varname>emacsWithPackages</varname> is not enough, as this
-    package set has some priorities imposed on packages (with the lowest
-    priority assigned to Melpa Unstable, and the highest for packages manually
-    defined in <filename>pkgs/top-level/emacs-packages.nix</filename>). But you
-    can't control this priorities when some package is installed as a
-    dependency. You can override it on per-package-basis, providing all the
-    required dependencies manually - but it's tedious and there is always a
-    possibility that an unwanted dependency will sneak in through some other
-    package. To completely override such a package you can use
-    <varname>overrideScope'</varname>.
-   </para>
-
-<screen>
-overrides = self: super: rec {
-  haskell-mode = self.melpaPackages.haskell-mode;
-  ...
-};
-((emacsPackagesNgGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
-  # here both these package will use haskell-mode of our own choice
-  ghc-mod
-  dante
-])
-</screen>
-  </section>
- </section>
  <section xml:id="sec-weechat">
   <title>Weechat</title>
 
@@ -762,64 +456,6 @@ stdenv.mkDerivation {
 }</programlisting>
   </para>
  </section>
- <section xml:id="sec-citrix">
-  <title>Citrix Receiver</title>
-
-  <para>
-   The <link xlink:href="https://www.citrix.com/products/receiver/">Citrix
-   Receiver</link> is a remote desktop viewer which provides access to
-   <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link>
-   installations.
-  </para>
-
-  <section xml:id="sec-citrix-base">
-   <title>Basic usage</title>
-
-   <para>
-    The tarball archive needs to be downloaded manually as the licenses
-    agreements of the vendor need to be accepted first. This is available at
-    the
-    <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">download
-    page at citrix.com</link>. Then run <literal>nix-prefetch-url
-    file://$PWD/linuxx64-$version.tar.gz</literal>. With the archive available
-    in the store the package can be built and installed with Nix.
-   </para>
-
-   <para>
-    <emphasis>Note: it's recommended to install <literal>Citrix
-    Receiver</literal> using <literal>nix-env -i</literal> or globally to
-    ensure that the <literal>.desktop</literal> files are installed properly
-    into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to
-    open <literal>.ica</literal> files automatically from the browser to start
-    a Citrix connection.</emphasis>
-   </para>
-  </section>
-
-  <section xml:id="sec-citrix-custom-certs">
-   <title>Custom certificates</title>
-
-   <para>
-    The <literal>Citrix Receiver</literal> in <literal>nixpkgs</literal> trusts
-    several certificates
-    <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the
-    Mozilla database</link> by default. However several companies using Citrix
-    might require their own corporate certificate. On distros with imperative
-    packaging these certs can be stored easily in
-    <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>,
-    however this directory is a store path in <literal>nixpkgs</literal>. In
-    order to work around this issue the package provides a simple mechanism to
-    add custom certificates without rebuilding the entire package using
-    <literal>symlinkJoin</literal>:
-<programlisting>
-<![CDATA[with import <nixpkgs> { config.allowUnfree = true; };
-let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in
-citrix_receiver.override {
-  inherit extraCerts;
-}]]>
-</programlisting>
-   </para>
-  </section>
- </section>
  <section xml:id="sec-ibus-typing-booster">
   <title>ibus-engines.typing-booster</title>
 
@@ -891,33 +527,6 @@ citrix_receiver.override {
    </para>
   </section>
  </section>
- <section xml:id="dlib">
-  <title>DLib</title>
-
-  <para>
-    <link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which
-    provides several machine learning algorithms.
-  </para>
-
-  <section xml:id="compiling-without-avx-support">
-   <title>Compiling without AVX support</title>
-
-   <para>
-     Especially older CPUs don't support
-     <link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link>
-     (<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to
-     optimize their algorithms.
-   </para>
-
-   <para>
-    On the affected hardware errors like <literal>Illegal instruction</literal> will occur.
-    In those cases AVX support needs to be disabled:
-<programlisting>self: super: {
-  dlib = super.dlib.override { avxSupport = false; };
-}</programlisting>
-   </para>
-  </section>
- </section>
  <section xml:id="sec-nginx">
   <title>Nginx</title>