(address . guix-patches@gnu.org)(name . Andreas Enge)(address . andreas@enge.fr)
568f6058b52263ac5bbf06580a3fdb4d701e68fa.1693594575.git.mail@nicolasgoaziou.fr
* doc/guix.texi (Invoking guix import): Mention "--recursive" option.
(Using TeX and LaTeX): Improve documentation of modular TeX Live. Insist on
the incompatibility with TEXLIVE package, and expound part about collections
and schemes. Also fix the call to `tlmgr', which does not need to happen from
a "guix shell" invocation.
Co-authored-by: Andreas Enge <andreas@enge.fr>
---
doc/guix.texi | 124 +++++++++++++++++++-------------------------------
1 file changed, 47 insertions(+), 77 deletions(-)
Toggle diff (195 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 04e5875925..e716e22efc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -14165,6 +14165,16 @@ Invoking guix import
guix import texlive fontspec
@end example
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
@item json
@cindex JSON, import
Import package metadata from a local JSON file. Consider the following
@@ -45862,47 +45872,44 @@ Using TeX and LaTeX
Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
related typesetting systems, taken from the
@uref{https://www.tug.org/texlive/, @TeX{} Live distribution}. However,
-because @TeX{} Live is so huge and because finding your way in this maze
-is tricky, we thought that you, dear user, would welcome guidance on how
-to deploy the relevant packages so you can compile your @TeX{} and
-@LaTeX{} documents.
+because @TeX{} Live is so huge and because finding one's way in this
+maze is tricky, so this section provides some guidance on how to deploy
+the relevant packages to compile @TeX{} and @LaTeX{} documents.
-@TeX{} Live currently comes in two flavors in Guix:
+@TeX{} Live currently comes in two mutually exclusive flavors in Guix:
@itemize
@item
The ``monolithic'' @code{texlive} package: it comes with @emph{every
-single @TeX{} Live package} (more than 7,000 of them), but it is huge
-(more than 4@tie{}GiB for a single package!).
+single @TeX{} Live package} (they are more or less 4,200), but it is
+huge (more than 4@tie{}GiB for a single package!).
@item
-The ``modular'' @samp{texlive-} packages: you start off with
-a combination of @TeX{} Live @dfn{collections} and
-@dfn{schemes}---``meta-packages'' such as
-@code{texlive-collection-fontsrecommended}, or
-@code{texlive-collection-context}, that provide the set of packages
-needed in this particular domain, schemes being the name for collections
-of such collections. This grants you core functionality and the main
-commands---@command{pdflatex}, @command{dvips}, @command{luatex},
-@command{mf}, etc. You can then complete your selection with additional
-collections or individual packages that provide just the features you
-need---@code{texlive-listings} for the @code{listings} package,
-@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ, and
-so on.
+A ``modular'' @TeX{} Live distribution, in which you only install the
+packages, always prefixed with @samp{texlive-}, you need.
@end itemize
-We recommend using the modular package set because it is much less
-resource-hungry. To build your documents, you would use commands such
-as:
+So to insist, these two flavors cannot be combined. If in the modular
+setting your document does not compile, the solution is not to add the
+monolithic @code{texlive} package, but to add the set of missing
+packages from the modular distribution.
+
+Building a coherent system that provides all the essential tools and, at
+the same time, satisfies all of its internal dependencies can be
+a difficult task. It is therefore recommended to start with sets of
+packages, called @dfn{collections}, and @dfn{schemes}, the name for
+collections of collections. The following command lists available
+schemes and collections (@pxref{guix-search,, Invoking guix package}):
@example
-guix shell texlive-scheme-basic texlive-cm-super -- pdflatex doc.tex
+guix search texlive-\(scheme\|collection\) | recsel -p name,description
@end example
-You can quickly end up with unreasonably long command lines though. The
-solution is to instead write a manifest, for example like this one,
-which would probably be a reasonable starting point for a French
-@LaTeX{} user:
+If needed, you may then complete your system with individual packages,
+particularly when they belong to a large collection.
+
+For instance, the following manifest is a reasonable, yet frugal
+starting point for a French @LaTeX{} user:
@lisp
(specifications->manifest
@@ -45911,31 +45918,16 @@ Using TeX and LaTeX
"texlive-scheme-basic"
"texlive-collection-latexrecommended"
"texlive-collection-fontsrecommended"
-
"texlive-babel-french"
- ;; PGF/TikZ
- "texlive-pgf"
-
;; Additional font.
"texlive-kpfonts"))
@end lisp
-You can then pass it to any command with the @option{-m} option:
-
-@example
-guix shell -m manifest.scm -- pdflatex doc.tex
-@end example
-
-@xref{Writing Manifests}, for more on manifests. In the future, we plan
-to provide more collections and schemes. That will allow you to list
-fewer packages.
-
-The main difficulty here is that using the modular package set forces
-you to select precisely the packages that you need. You can use
-@command{guix search}, but finding the right package can prove to be
-tedious. When a package is missing, @command{pdflatex} and similar
-commands fail with an obscure message along the lines of:
+If you come across a document that does not compile in such a basic
+setting, the main difficulty is finding the missing packages. In this
+case, @command{pdflatex} and similar commands tend to fail with obscure
+error messages along the lines of:
@example
doc.tex: File `tikz.sty' not found.
@@ -45951,7 +45943,7 @@ Using TeX and LaTeX
@end example
How do you determine what the missing package is? In the first case,
-you'll find the answer by running:
+you will find the answer by running:
@example
$ guix search texlive tikz
@@ -45961,11 +45953,11 @@ Using TeX and LaTeX
@end example
In the second case, @command{guix search} turns up nothing. Instead,
-you can search the @TeX{} Live package database using the @command{tlmgr}
-command:
+you can search the @TeX{} Live package database using the
+@command{tlmgr} command:
@example
-$ guix shell texlive-bin -- tlmgr info phvr7t
+$ tlmgr info phvr7t
tlmgr: cannot find package phvr7t, searching for other matches:
Packages containing `phvr7t' in their title/description:
@@ -45980,32 +45972,10 @@ Using TeX and LaTeX
texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
@end example
-The file is available in the @TeX{} Live @code{helvetic} package, which is
-known in Guix as @code{texlive-helvetic}. Quite a ride, but we found
-it!
-
-There is one important limitation though: Guix currently provides a
-subset of the @TeX{} Live packages. If you stumble upon a missing
-package, you can try and import it (@pxref{Invoking guix import}):
-
-@example
-guix import texlive @var{package}
-@end example
-
-Additional options include:
-
-@table @code
-@item --recursive
-@itemx -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
-@end table
-
-@quotation Note
-@TeX{} Live packaging is still very much work in progress, but you can
-help! @xref{Contributing}, for more information.
-@end quotation
+@noindent
+The file is available in the @TeX{} Live @code{helvetic} package, which
+is known in Guix as @code{texlive-helvetic}. Quite a ride, but you
+found it!
@node Security Updates
@chapter Security Updates
base-commit: f5c4db45e95cf8ea23c2c133ed2535ca94a06f7d
--
2.41.0