69/69: gnu: Update commentary section in "tex.scm".

[guix-commits]

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

commit fa5229cfe8717cc609f1c4c9f11c9ff48be31eed
Author: Nicolas Goaziou <mail@nicolasgoaziou.fr>
AuthorDate: Tue May 28 15:33:49 2024 +0200

    gnu: Update commentary section in "tex.scm".
    
    * gnu/packages/tex.scm: Describe new bootstrap story in "tex.scm".
    
    Change-Id: I713c225c02169deec077ef06f165d559b2625779
---
 gnu/packages/tex.scm | 74 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 53 insertions(+), 21 deletions(-)

diff --git a/gnu/packages/tex.scm b/gnu/packages/tex.scm
index 2c991fd328..fc74fecb4e 100644
--- a/gnu/packages/tex.scm
+++ b/gnu/packages/tex.scm
@@ -113,28 +113,60 @@
 
 ;;; Commentary:
 ;;;
-;;; This module aims at being as faithful as possible to TeX Live
-;;; distribution.  Yet, some of the packages in this module are Guix specific.
-;;; 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.  It aims
+;;; at being as faithful as possible to TeX Live distribution.  Yet, some of
+;;; the packages defined here are Guix specific.  The following paragraphs
+;;; describe them.
+;;;
+;;; Modular TeX Live source is located in TEXLIVE-SOURCE, which is therefore
+;;; the starting point of any TeX Live update.  This is first used to build
+;;; TEXLIVE-LIBKPATHSEA and TEXLIVE-LIBPTEXENC.
+;;;
+;;; Both TEXLIVE-SOURCE and TEXLIVE-LIBKPATHSEA---which takes care of creating
+;;; a search path for GUIX_TEXMF environment variable---are used to compile
+;;; TEXLIVE-BIN.  In turn, TEXLIVE-BIN propagates TEXLIVE-SCRIPTS, which
+;;; contains core scripts and related files, including "texlive.tldb"
+;;; database.  TEXLIVE-BIN is a mandatory native input in the `texlive' build
+;;; system.
+;;;
+;;; 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 TEXLIVE-BIN package provides a few Web2C tools, Metafont and some TeX
+;;; engines---i.e, TeX, pdfLaTeX, LuaTeX and LuaHBTeX.  The rest of the
+;;; binaries are built in separate packages, from TEXLIVE-SOURCE, and possibly
+;;; with the help of TEXLIVE-LIBKPATHSEA and TEXLIVE-LIBPTEXENC.  Those
+;;; packages inherit their phases from TEXLIVE-BIN.  As a convention, the
+;;; package named "texlive-NAME-bin" provides binaries for "texlive-NAME",
+;;; TEXLIVE-LATEX-BIN being the obvious exception to this scheme.
+;;;
+;;; The following piece of art illustrates the bootstrap process of the
+;;; modular Guix TeX Live distribution.  All "texlive-" prefixes have been
+;;; dropped for brevity.
+;;;
 ;;;
-;;; On the one hand, the monolithic TeX Live merges TEXLIVE-BIN-FULL and
-;;; TEXLIVE-TEXMF in order to create TEXLIVE.
+;;;           ,-- libptexenc----------------------------.
+;;;           |                                         |
+;;;           |                                         |
+;;;  source --|                    ,------- all "*-bin" minus latex-bin
+;;;    |      |                    |         _________________________
+;;;    |      |                    |                    |
+;;;    |      `-- libkpathsea --.  |                    |
+;;;    |                        |--|         (inherit phases from bin)
+;;;    `------------------------’  |
+;;;                                |
+;;;                                |
+;;;                                `------- bin -- ... docstrip ... -- 
latex-bin
+;;;                                          |      ___________________________
+;;;  scripts --------(propagated)------------’                   |
+;;;                                                              |
+;;;                                                  (#: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 +185,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 "texlive-NAME" package matches "NAME" TeX Live package, as
+;;; defined in the "texlive.tlpdb" database.
 ;;;
 ;;; Code: