texlive: document in nixpkgs manual

Fixes #13240. It's not really better than source-code comments it replaced,
but it's in a better accessible place.

3 files changed, 63 insertions, 25 deletions

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 7922f2a5f5a..ab62afa40d6 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -23,6 +23,7 @@ such as Perl or Haskell.  These are described in this chapter.</para>
 <xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md  -->
 <xi:include href="r.xml" /> <!-- generated from ../../pkgs/development/r-modules/README.md  -->
 <xi:include href="qt.xml" />
+<xi:include href="texlive.xml" />
 
 
 </chapter>
diff --git a/doc/languages-frameworks/texlive.xml b/doc/languages-frameworks/texlive.xml
new file mode 100644
index 00000000000..0e3c1dd13d7
--- /dev/null
+++ b/doc/languages-frameworks/texlive.xml
@@ -0,0 +1,59 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-language-texlive">
+
+<title>TeX Live</title>
+
+<para>Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute <varname>texlive</varname>.</para>
+<section><title>User's guide</title>
+  <itemizedlist>
+    <listitem><para>
+      For basic usage just pull <varname>texlive.combined.scheme-basic</varname> for an environment with basic LaTeX support.</para></listitem>
+    <listitem><para>
+      It typically won't work to use separately installed packages together.
+      Instead, you can build a custom set of packages like this:
+      <programlisting>
+texlive.combine {
+  inherit (texlive) scheme-small collection-langkorean algorithms cm-super;
+}
+      </programlisting>
+      There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).
+    </para></listitem>
+    <listitem><para>
+      By default you only get executables and files needed during runtime, and a little documentation for the core packages.  To change that, you need to add <varname>pkgFilter</varname> function to <varname>combine</varname>.
+      <programlisting>
+texlive.combine {
+  # inherit (texlive) whatever-you-want;
+  pkgFilter = pkg:
+    pkg.tlType == "run" || pkg.tlType == "bin" || pkg.pname == "cm-super";
+  # elem tlType [ "run" "bin" "doc" "source" ]
+  # there are also other attributes: version, name
+}
+      </programlisting>
+    </para></listitem>
+    <listitem><para>
+      You can list packages e.g. by <command>nix-repl</command>.
+      <programlisting>
+$ nix-repl
+nix-repl> texlive.collection-&lt;TAB>
+      </programlisting>
+    </para></listitem>
+  </itemizedlist>
+</section>
+
+<section><title>Known problems</title>
+  <itemizedlist>
+    <listitem><para>
+      Some tools are still missing, e.g. luajittex;</para></listitem>
+    <listitem><para>
+      some apps aren't packaged/tested yet (asymptote, biber, etc.);</para></listitem>
+    <listitem><para>
+      feature/bug: when a package is rejected by <varname>pkgFilter</varname>, its dependencies are still propagated;</para></listitem>
+    <listitem><para>
+      in case of any bugs or feature requests, file a github issue or better a pull request and /cc @vcunat.</para></listitem>
+  </itemizedlist>
+</section>
+
+
+</section>
+
diff --git a/pkgs/tools/typesetting/tex/texlive-new/default.nix b/pkgs/tools/typesetting/tex/texlive-new/default.nix
index 5fe52ba07ba..fbf4adde2ae 100644
--- a/pkgs/tools/typesetting/tex/texlive-new/default.nix
+++ b/pkgs/tools/typesetting/tex/texlive-new/default.nix
@@ -1,29 +1,7 @@
-/* (new) TeX Live user docs
-  - Basic usage: just pull texlive.combined.scheme-basic
-  for an environment with basic LaTeX support.
-  There are all the schemes as defined upstream (with tiny differences, perhaps).
-  - You can compose your own collection like this:
-    texlive.combine {
-      inherit (texlive) scheme-small collection-langkorean algorithms cm-super;
-    }
-  - By default you only get executables and files needed during runtime,
-  and a little documentation for the core packages.
-  To change that, you need to add `pkgFilter` function to `combine`.
-    texlive.combine {
-      # inherit (texlive) whatever-you-want;
-      pkgFilter = pkg:
-        pkg.tlType == "run" || pkg.tlType == "bin" || pkg.pname == "cm-super";
-     # elem tlType [ "run" "bin" "doc" "source" ]
-     # there are also other attributes: version, name
-    }
-  - Known bugs:
-    * some tools are still missing, e.g. luajittex
-    * some apps aren't packaged/tested yet (xdvi, asymptote, biber, etc.)
-    * feature/bug: when a package is rejected by pkgFilter,
-      its dependencies are still propagated
-    * in case of any bugs or feature requests, file a github issue and /cc @vcunat
+/* TeX Live user docs
+  - source: ../../../../../doc/languages-frameworks/texlive.xml
+  - current html: http://nixos.org/nixpkgs/manual/#sec-language-texlive
 */
-
 { stdenv, lib, fetchurl, runCommand, writeText, buildEnv
 , callPackage, ghostscriptX, harfbuzz, poppler_min
 , makeWrapper, perl, python, ruby