[PATCH] doc: manual: Update TeX Live-related sections.

  • Done
  • quality assurance status badge
Details
2 participants
  • Andreas Enge
  • Nicolas Goaziou
Owner
unassigned
Submitted by
Nicolas Goaziou
Severity
normal
N
N
Nicolas Goaziou wrote on 1 Sep 2023 20:56
(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
N
N
Nicolas Goaziou wrote on 1 Sep 2023 22:39
[PATCH v2] doc: manual: Update TeX Live-related sections.
(address . 65683@debbugs.gnu.org)(name . Andreas Enge)(address . andreas@enge.fr)
e00569026839dd7930c09cf344dc31a5f634edbe.1693600755.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>
---

v2: Mention that `texlive' + `texlive-biber' is OK.

doc/guix.texi | 127 ++++++++++++++++++++------------------------------
1 file changed, 50 insertions(+), 77 deletions(-)

Toggle diff (198 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 04e5875925..e012f7702d 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,47 @@ 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@footnote{No rule
+without exception! As the monolithic texlive 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.
+
+For instance, the following manifest is a reasonable, yet frugal
+starting point for a French @LaTeX{} user:
@lisp
(specifications->manifest
@@ -45911,31 +45921,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 +45946,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 +45956,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 +45975,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
A
A
Andreas Enge wrote on 4 Sep 2023 09:49
(name . Nicolas Goaziou)(address . mail@nicolasgoaziou.fr)(address . 65683@debbugs.gnu.org)
ZPWMCQYPPBa-WdJn@jurong
Hello,

I think you can go ahead, as the person who packaged all of Texlive you are
clearly most competent for writing the documentation. I have looked at it,
which makes for a second opinion, so I would not know what else to wait for.

Andreas
N
N
Nicolas Goaziou wrote on 4 Sep 2023 13:15
Re: [bug#65683] [PATCH v2] doc: manual: Update TeX Live-related sections.
(name . Andreas Enge)(address . andreas@enge.fr)(address . 65683-done@debbugs.gnu.org)
87msy29ol9.fsf@nicolasgoaziou.fr
Hello,

Andreas Enge <andreas@enge.fr> writes:

Toggle quote (5 lines)
> I think you can go ahead, as the person who packaged all of Texlive you are
> clearly most competent for writing the documentation. I have looked at it,
> which makes for a second opinion, so I would not know what else to
> wait for.

I know that the contents are technically correct. I think I was waiting
for some possible feedback about clarity, in particular from people less
familiar with that part of the code.

In any case, I pushed the documentation change with slight
modifications, in particular in the manifest example.

Thanks!

Regards,
--
Nicolas Goaziou
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 65683@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 65683
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch