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.

2 files changed, 60 insertions, 0 deletions

diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 7922f2a5f5ae..ab62afa40d61 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 000000000000..0e3c1dd13d72
--- /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>
+