53/53: gnu: Updated commentary in "tex.scm".

[guix-commits]

ngz pushed a commit to branch tex-team
in repository guix.

commit b8f3014d9c8a71211641d83df8e2649ec79ab21e
Author: Nicolas Goaziou <mail@nicolasgoaziou.fr>
AuthorDate: Wed May 8 18:38:42 2024 +0200

    gnu: Updated commentary in "tex.scm".
    
    * gnu/packages/tex.scm: Remove part about monolithic TEXLIVE package.  
Mention
    TEXLIVE-SOURCE and goals for TEXLIVE-BIN, including packaging scheme for
    un-bundled libraries.
    
    Change-Id: I16adc06c808bef666cdd2393c046c6564481a22c
---
 gnu/packages/tex.scm | 60 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 43 insertions(+), 17 deletions(-)

diff --git a/gnu/packages/tex.scm b/gnu/packages/tex.scm
index 31524c4ce3..fe860c35c5 100644
--- a/gnu/packages/tex.scm
+++ b/gnu/packages/tex.scm
@@ -118,23 +118,49 @@
 ;;; The following paragraphs describe them.
 ;;;
 ;;; Guix provides two different TeX Live systems: one monolithic, the TEXLIVE
-;;; package, and the other modular.  Both are built from TEXLIVE-LIBKPATHSEA,
-;;; which is therefore the starting of any TeX Live update.  Both also rely on
-;;; TEXLIVE-SCRIPTS, which contains core scripts and related files---although
-;;; monolithic TeX Live only makes use of its source.  At that point, both
-;;; systems diverge.
+;;; package, and the other modular.  This module is about the latter.
 ;;;
-;;; On the one hand, the monolithic TeX Live merges TEXLIVE-BIN-FULL and
-;;; TEXLIVE-TEXMF in order to create TEXLIVE.
+;;; Modular TeX Live source is located in TEXLIVE-SOURCE, which is therefore
+;;; the starting of any TeX Live update.  This is first used to build
+;;; TEXLIVE-LIBKPATHSEA and TEXLIVE-LIBPTEXENC. It also relies on
+;;; TEXLIVE-SCRIPTS, which contains core scripts and related files.
+;;;
+;;; Both TEXLIVE-LIBKPATHSEA, which takes care of populating GUIX_TEXMF
+;;; environment variable, and TEXLIVE-LIBPTEXENC are used to compile
+;;; TEXLIVE-BIN.  Since it also propagates TEXLIVE-SCRIPTS, it really is the
+;;; core of the Guix TeX Live distribution.  Therefore, TEXLIVE-BIN is
+;;; a mandatory native input in the `texlive' build system.
+;;;
+;;; TEXLIVE-BIN includes only "web2c" binaries.  The other ones are compiled
+;;; directly from TEXLIVE-SOURCE, either as a regular TeX Live package---if it
+;;; only contains binaries and their man pages---or as a private
+;;; "texlive-NAME-bin" package used as a native input for public
+;;; "texlive-NAME" package.
+;;;
+;;; Then the system builds its way towards regular TEXLIVE-LATEX-BIN package,
+;;; which is a convenient native input---that can be ignored or replaced using
+;;; `texlive-latex-bin?' keyword argument---for most TeX Live packages.
+;;; Packages used to build TEXLIVE-LATEX-BIN, however, may need the
+;;; TEXLIVE-DOCSTRIP package to be able to generate their runfiles.  Their
+;;; `texlive-latex-bin?' keyword argument must be set to #f, too.
+;;;
+;;; The following piece of art illustrates the bootstrap process of the Guix
+;;; TeX Live distribution.  All "texlive-" prefixes have been dropped for
+;;; clarity.
+;;;
+;;;
+;;;   source ---- libkpathsea --|
+;;;          \                  |-- bin ---|
+;;;           \__ libptexenc ---|          |
+;;;                                        |-- ... docstrip ... -- latex-bin
+;;;                                        |          +
+;;;   scripts -----------------------------|      latex-bin
+;;;                                              dependencies
+;;;                                            ________________
+;;;                                                   |
+;;;                                                   |
+;;;                                        (#:texlive-latex-bin? #f)
 ;;;
-;;; On the other hand, modular TeX Live relies on TEXLIVE-BIN, which is
-;;; provided as a mandatory native input in the texlive build system.  Unlike
-;;; TEXLIVE-BIN-FULL, it doesn't provide any script (but still include all the
-;;; binaries; this might change in the future).  Then the system builds its
-;;; way towards regular `texlive-latex-bin' package, which is a convenient
-;;; native input (that can be ignored) for most TeX Live packages.  Those
-;;; earlier in the build chain need the TEXLIVE-DOCSTRIP package to still be
-;;; able to generate their runfiles.
 ;;;
 ;;; Default font map files are updated in a profile hook (see
 ;;; `texlive-font-maps' in "profiles.scm").  However, this option is not
@@ -153,8 +179,8 @@
 ;;; TEXLIVE-HYPHEN-COMPLETE, and all formats, being built with it, include all
 ;;; rules right from the start.
 ;;;
-;;; Any other "texlive-name" package matches the "name" TeX Live package, as
-;;; defined in the "texlive.tlpdb" file.
+;;; Any other public "texlive-NAME" package matches "NAME" TeX Live package,
+;;; as defined in the "texlive.tlpdb" file.
 ;;;
 ;;; Code: