53/54: gnu: Update commentary in "tex.scm".

[guix-commits]

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

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

    gnu: Update commentary in "tex.scm".
    
    * gnu/packages/tex.scm: Remove part about monolithic TEXLIVE package.
    Describe more accurately the bootstrap story of modular TeX Live.
    
    Change-Id: I16adc06c808bef666cdd2393c046c6564481a22c
---
 gnu/packages/tex.scm | 68 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 47 insertions(+), 21 deletions(-)

diff --git a/gnu/packages/tex.scm b/gnu/packages/tex.scm
index e7f56e724f..7ad68d91ec 100644
--- a/gnu/packages/tex.scm
+++ b/gnu/packages/tex.scm
@@ -113,28 +113,54 @@
 
 ;;; 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 of any TeX Live update.  This is first used to build
+;;; TEXLIVE-LIBKPATHSEA, TEXLIVE-LIBPTEXENC and TEXLIVE-DVIPDFMX-BIN.
+;;;
+;;; TEXLIVE-LIBKPATHSEA---which takes care of populating GUIX_TEXMF
+;;; environment variable---, TEXLIVE-LIBPTEXENC and TEXLIVE-DVIPDFMX-BIN are
+;;; used to compile TEXLIVE-BIN.  In turn, TEXLIVE-BIN propagates
+;;; TEXLIVE-SCRIPTS, which contains core scripts and related files (including
+;;; "texlive.tldb").  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 following piece of art illustrates the bootstrap process of the
+;;; modular Guix TeX Live distribution.  All "texlive-" prefixes have been
+;;; dropped for brevity.
+;;;
+;;;
+;;;  source ------ libkpathsea ---|
+;;;         \                     |         |
+;;;          \____ libptexenc ----|-- bin --|
+;;;           \                   |         |
+;;;            \__ dvipdfmx-bin --|         |-- ... docstrip ... -- latex-bin
+;;;                                         |          +
+;;;  scripts -------------------------------|      latex-bin
+;;;                                         |     dependencies
+;;;                                             \______________/
+;;;                                                    |
+;;;                                                    |
+;;;                                        (#:texlive-latex-bin? #f)
 ;;;
-;;; On the one hand, the monolithic TeX Live merges TEXLIVE-BIN-FULL and
-;;; TEXLIVE-TEXMF in order to create TEXLIVE.
 ;;;
-;;; 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.
+;;; Note that 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.
 ;;;
 ;;; 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: