aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2023-09-01 22:39:15 +0200
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2023-09-04 13:03:59 +0200
commit8d70ff3a49f7cdf0eab93b3a1c54ec2f016afc4a (patch)
treeb266f4e07901299a11a8f940b2f6db0a63dda0e4 /doc
parentbedcdf0fb5ac035f696790827679406c7146396c (diff)
downloadguix-8d70ff3a49f7cdf0eab93b3a1c54ec2f016afc4a.tar
guix-8d70ff3a49f7cdf0eab93b3a1c54ec2f016afc4a.tar.gz
doc: manual: Update TeX Live-related sections.
* 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>
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi134
1 files changed, 55 insertions, 79 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 9e79641736..a6b74ce9c7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -14175,6 +14175,16 @@ TeX package:
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
@@ -45928,47 +45938,48 @@ will not have the desired effect. @xref{Package Transformation Options,
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} (roughly 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@footnote{No rule
+without exception! As the monolithic @TeX{} Live does not contain the
+@command{biber} executable, it is okay to combine it with
+@code{texlive-biber}, which does.}. 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 you're not otherwise
+interested in.
+
+For instance, the following manifest is a reasonable, yet frugal
+starting point for a French @LaTeX{} user:
@lisp
(specifications->manifest
@@ -45977,31 +45988,18 @@ which would probably be a reasonable starting point for a French
"texlive-scheme-basic"
"texlive-collection-latexrecommended"
"texlive-collection-fontsrecommended"
-
"texlive-babel-french"
- ;; PGF/TikZ
- "texlive-pgf"
-
- ;; Additional font.
- "texlive-kpfonts"))
+ ;; From "latexextra" collection.
+ "texlive-tabularray"
+ ;; From "binextra" collection.
+ "texlive-texdoc"))
@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.
@@ -46017,7 +46015,7 @@ kpathsea: Running mktexmf phvr7t
@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
@@ -46027,11 +46025,11 @@ version: 59745
@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:
@@ -46046,32 +46044,10 @@ tex4ht:
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