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>
This commit is contained in:
		
							parent
							
								
									bedcdf0fb5
								
							
						
					
					
						commit
						8d70ff3a49
					
				
					 1 changed files with 55 additions and 79 deletions
				
			
		
							
								
								
									
										134
									
								
								doc/guix.texi
									
										
									
									
									
								
							
							
						
						
									
										134
									
								
								doc/guix.texi
									
										
									
									
									
								
							| 
						 | 
					@ -14175,6 +14175,16 @@ TeX package:
 | 
				
			||||||
guix import texlive fontspec
 | 
					guix import texlive fontspec
 | 
				
			||||||
@end example
 | 
					@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
 | 
					@item json
 | 
				
			||||||
@cindex JSON, import
 | 
					@cindex JSON, import
 | 
				
			||||||
Import package metadata from a local JSON file.  Consider the following
 | 
					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
 | 
					Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
 | 
				
			||||||
related typesetting systems, taken from the
 | 
					related typesetting systems, taken from the
 | 
				
			||||||
@uref{https://www.tug.org/texlive/, @TeX{} Live distribution}.  However,
 | 
					@uref{https://www.tug.org/texlive/, @TeX{} Live distribution}.  However,
 | 
				
			||||||
because @TeX{} Live is so huge and because finding your way in this maze
 | 
					because @TeX{} Live is so huge and because finding one's way in this
 | 
				
			||||||
is tricky, we thought that you, dear user, would welcome guidance on how
 | 
					maze is tricky, so this section provides some guidance on how to deploy
 | 
				
			||||||
to deploy the relevant packages so you can compile your @TeX{} and
 | 
					the relevant packages to compile @TeX{} and @LaTeX{} documents.
 | 
				
			||||||
@LaTeX{} documents.
 | 
					 | 
				
			||||||
 | 
					
 | 
				
			||||||
@TeX{} Live currently comes in two flavors in Guix:
 | 
					@TeX{} Live currently comes in two mutually exclusive flavors in Guix:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
@itemize
 | 
					@itemize
 | 
				
			||||||
@item
 | 
					@item
 | 
				
			||||||
The ``monolithic'' @code{texlive} package: it comes with @emph{every
 | 
					The ``monolithic'' @code{texlive} package: it comes with @emph{every
 | 
				
			||||||
single @TeX{} Live package} (more than 7,000 of them), but it is huge
 | 
					single @TeX{} Live package} (roughly 4,200), but it is huge---more than
 | 
				
			||||||
(more than 4@tie{}GiB for a single package!).
 | 
					4@tie{}GiB for a single package!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
@item
 | 
					@item
 | 
				
			||||||
The ``modular'' @samp{texlive-} packages: you start off with
 | 
					A ``modular'' @TeX{} Live distribution, in which you only install the
 | 
				
			||||||
a combination of @TeX{} Live @dfn{collections} and
 | 
					packages, always prefixed with @samp{texlive-}, you need.
 | 
				
			||||||
@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.
 | 
					 | 
				
			||||||
@end itemize
 | 
					@end itemize
 | 
				
			||||||
 | 
					
 | 
				
			||||||
We recommend using the modular package set because it is much less
 | 
					So to insist, these two flavors cannot be combined@footnote{No rule
 | 
				
			||||||
resource-hungry.  To build your documents, you would use commands such
 | 
					without exception! As the monolithic @TeX{} Live does not contain the
 | 
				
			||||||
as:
 | 
					@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
 | 
					@example
 | 
				
			||||||
guix shell texlive-scheme-basic texlive-cm-super -- pdflatex doc.tex
 | 
					guix search texlive-\(scheme\|collection\) | recsel -p name,description
 | 
				
			||||||
@end example
 | 
					@end example
 | 
				
			||||||
 | 
					
 | 
				
			||||||
You can quickly end up with unreasonably long command lines though.  The
 | 
					If needed, you may then complete your system with individual packages,
 | 
				
			||||||
solution is to instead write a manifest, for example like this one,
 | 
					particularly when they belong to a large collection you're not otherwise
 | 
				
			||||||
which would probably be a reasonable starting point for a French
 | 
					interested in.
 | 
				
			||||||
@LaTeX{} user:
 | 
					
 | 
				
			||||||
 | 
					For instance, the following manifest is a reasonable, yet frugal
 | 
				
			||||||
 | 
					starting point for a French @LaTeX{} user:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
@lisp
 | 
					@lisp
 | 
				
			||||||
(specifications->manifest
 | 
					(specifications->manifest
 | 
				
			||||||
| 
						 | 
					@ -45977,31 +45988,18 @@ which would probably be a reasonable starting point for a French
 | 
				
			||||||
   "texlive-scheme-basic"
 | 
					   "texlive-scheme-basic"
 | 
				
			||||||
   "texlive-collection-latexrecommended"
 | 
					   "texlive-collection-latexrecommended"
 | 
				
			||||||
   "texlive-collection-fontsrecommended"
 | 
					   "texlive-collection-fontsrecommended"
 | 
				
			||||||
 | 
					 | 
				
			||||||
   "texlive-babel-french"
 | 
					   "texlive-babel-french"
 | 
				
			||||||
 | 
					
 | 
				
			||||||
   ;; PGF/TikZ
 | 
					   ;; From "latexextra" collection.
 | 
				
			||||||
   "texlive-pgf"
 | 
					   "texlive-tabularray"
 | 
				
			||||||
 | 
					   ;; From "binextra" collection.
 | 
				
			||||||
   ;; Additional font.
 | 
					   "texlive-texdoc"))
 | 
				
			||||||
   "texlive-kpfonts"))
 | 
					 | 
				
			||||||
@end lisp
 | 
					@end lisp
 | 
				
			||||||
 | 
					
 | 
				
			||||||
You can then pass it to any command with the @option{-m} option:
 | 
					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
 | 
				
			||||||
@example
 | 
					case, @command{pdflatex} and similar commands tend to fail with obscure
 | 
				
			||||||
guix shell -m manifest.scm -- pdflatex doc.tex
 | 
					error messages along the lines of:
 | 
				
			||||||
@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:
 | 
					 | 
				
			||||||
 | 
					
 | 
				
			||||||
@example
 | 
					@example
 | 
				
			||||||
doc.tex: File `tikz.sty' not found.
 | 
					doc.tex: File `tikz.sty' not found.
 | 
				
			||||||
| 
						 | 
					@ -46017,7 +46015,7 @@ kpathsea: Running mktexmf phvr7t
 | 
				
			||||||
@end example
 | 
					@end example
 | 
				
			||||||
 | 
					
 | 
				
			||||||
How do you determine what the missing package is?  In the first case,
 | 
					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
 | 
					@example
 | 
				
			||||||
$ guix search texlive tikz
 | 
					$ guix search texlive tikz
 | 
				
			||||||
| 
						 | 
					@ -46027,11 +46025,11 @@ version: 59745
 | 
				
			||||||
@end example
 | 
					@end example
 | 
				
			||||||
 | 
					
 | 
				
			||||||
In the second case, @command{guix search} turns up nothing.  Instead,
 | 
					In the second case, @command{guix search} turns up nothing.  Instead,
 | 
				
			||||||
you can search the @TeX{} Live package database using the @command{tlmgr}
 | 
					you can search the @TeX{} Live package database using the
 | 
				
			||||||
command:
 | 
					@command{tlmgr} command:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
@example
 | 
					@example
 | 
				
			||||||
$ guix shell texlive-bin -- tlmgr info phvr7t
 | 
					$ tlmgr info phvr7t
 | 
				
			||||||
tlmgr: cannot find package phvr7t, searching for other matches:
 | 
					tlmgr: cannot find package phvr7t, searching for other matches:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Packages containing `phvr7t' in their title/description:
 | 
					Packages containing `phvr7t' in their title/description:
 | 
				
			||||||
| 
						 | 
					@ -46046,32 +46044,10 @@ tex4ht:
 | 
				
			||||||
        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
 | 
					        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
 | 
				
			||||||
@end example
 | 
					@end example
 | 
				
			||||||
 | 
					
 | 
				
			||||||
The file is available in the @TeX{} Live @code{helvetic} package, which is
 | 
					@noindent
 | 
				
			||||||
known in Guix as @code{texlive-helvetic}.  Quite a ride, but we found
 | 
					The file is available in the @TeX{} Live @code{helvetic} package, which
 | 
				
			||||||
it!
 | 
					is known in Guix as @code{texlive-helvetic}.  Quite a ride, but you
 | 
				
			||||||
 | 
					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
 | 
					 | 
				
			||||||
 | 
					
 | 
				
			||||||
@node Security Updates
 | 
					@node Security Updates
 | 
				
			||||||
@chapter Security Updates
 | 
					@chapter Security Updates
 | 
				
			||||||
| 
						 | 
					
 | 
				
			||||||
		Reference in a new issue