GNU bug report logs - #65683
[PATCH] doc: manual: Update TeX Live-related sections.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 65683 in the body.
You can then email your comments to 65683 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: guix-patches <at> gnu.org
Cc: Andreas Enge <andreas <at> enge.fr>
Subject: [PATCH] doc: manual: Update TeX Live-related sections.
Date: Fri,  1 Sep 2023 20:56:15 +0200

* 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 <at> enge.fr>
---
 doc/guix.texi | 124 +++++++++++++++++++-------------------------------
 1 file changed, 47 insertions(+), 77 deletions(-)

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 <at> tie{}GiB for a single package!).
+single @TeX{} Live package} (they are more or less 4,200), but it is
+huge (more than 4 <at> 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

Message #8 received at 65683 <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: 65683 <at> debbugs.gnu.org
Cc: Andreas Enge <andreas <at> enge.fr>
Subject: [PATCH v2] doc: manual: Update TeX Live-related sections.
Date: Fri,  1 Sep 2023 22:39:15 +0200

* 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 <at> enge.fr>
---

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

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

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 <at> tie{}GiB for a single package!).
+single @TeX{} Live package} (they are more or less 4,200), but it is
+huge (more than 4 <at> 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 <at> 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

Message #11 received at 65683 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Enge <andreas <at> enge.fr>
To: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
Cc: 65683 <at> debbugs.gnu.org
Subject: Re: [PATCH v2] doc: manual: Update TeX Live-related sections.
Date: Mon, 4 Sep 2023 09:49:29 +0200

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

Message #16 received at 65683-done <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: Andreas Enge <andreas <at> enge.fr>
Cc: 65683-done <at> debbugs.gnu.org
Subject: Re: [bug#65683] [PATCH v2] doc: manual: Update TeX Live-related
 sections.
Date: Mon, 04 Sep 2023 13:15:14 +0200

Hello,

Andreas Enge <andreas <at> enge.fr> writes:

> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.