[latex3-commits] [git/LaTeX3-latex3-latex3] master: Revise expl3.pdf on distribution (c96240306)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/c962403065f658753a578cd13f22eb82b1bc46b2

>---------------------------------------------------------------

commit c962403065f658753a578cd13f22eb82b1bc46b2
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jan 8 09:57:30 2020 +0000

    Revise expl3.pdf on distribution


>---------------------------------------------------------------

c962403065f658753a578cd13f22eb82b1bc46b2
 l3kernel/expl3.dtx | 103 ++++++++++++-----------------------------------------
 1 file changed, 22 insertions(+), 81 deletions(-)

diff --git a/l3kernel/expl3.dtx b/l3kernel/expl3.dtx
index 26df99201..c5689241b 100644
--- a/l3kernel/expl3.dtx
+++ b/l3kernel/expl3.dtx
@@ -790,9 +790,8 @@
 % \section{The distribution}
 %
 % At present, the \pkg{expl3} modules are designed to be loaded on top
-% of \LaTeXe{}. In time, a \LaTeX3 format will be produced based on this
-% code. This allows the code to be used in \LaTeXe{} packages \emph{now}
-% while a stand-alone \LaTeX3 is developed.
+% of \LaTeXe{}. In time, a \LaTeX3 format may be produced based on this
+% code.
 %
 % \begin{bfseries}
 %   While \pkg{expl3} is still experimental, the bundle is now regarded
@@ -802,87 +801,29 @@
 %   \pkg{expl3}.
 % \end{bfseries}
 %
-% New modules will be added to the distributed version of \pkg{expl3}
-% as they reach maturity. At present, the \pkg{expl3} bundle consists
-% of a number of modules, most of which are loaded by including the
-% line:
+% The distribution of \pkg{expl3} is split up into three packages on
+% CTAN: \pkg{l3kernel}, \pkg{l3packages} and \pkg{l3experimental}.
+% For historical reasons, 
 % \begin{verbatim}
 %   \RequirePackage{expl3}
 % \end{verbatim}
-% in a \LaTeXe{} package, class or other file. The \pkg{expl3} modules
-% regarded as stable, and therefore suitable for basing real code on,
-% are as follows:
-%
-% \begin{description}
-%   \providecommand\explpkg[2]{\item[#1]#2}
-%   \explpkg{l3basics}{
-%     This contains the basic definition modules used
-%     by the other packages.
-%   }
-%   \explpkg{l3box}{
-%     Primitives for dealing with boxes.
-%   }
-%   \explpkg{l3clist}{
-%     Methods for manipulating comma-separated token lists.
-%   }
-%   \explpkg{l3coffins}{
-%     Augmented box constructs for alignment operations.
-%   }
-%   \explpkg{l3expan}{
-%     This is the argument expansion module discussed earlier in this
-%     document.
-%   }
-%   \explpkg{l3int}{
-%     This implements the integer data-type \texttt{int}.
-%   }
-%   \explpkg{l3keys}{
-%     For processing lists of the form
-%     \texttt{\{ key1=val1 , key2=val2 \}}, intended to work
-%     as a \LaTeX3 version of \pkg{xkeyval}/\pkg{kvoptions}, although
-%     with input syntax more like that of \pkg{pgfkeys}.
-%   }
-%   \explpkg{l3msg}{
-%     Communicating with the user: includes low-level hooks to allow
-%     messages to be filtered (higher-level interface for filtering
-%     to be written!).
-%   }
-%   \explpkg{l3names}{
-%     This sets up the basic naming scheme and renames all
-%     the \TeX{} primitives.
-%   }
-%   \explpkg{l3prg}{
-%     Program control structures such as boolean data type |bool|, generic
-%     do-while loops, and conditional flow.
-%   }
-%   \explpkg{l3prop}{
-%     This implements the data-type for \enquote{property lists} that are used, in
-%     particular, for storing key/value pairs.
-%   }
-%   \explpkg{l3quark}{
-%     A \enquote{quark} is a command that is defined to expand to
-%     itself!  Therefore they must never be expanded as this would generate an
-%     infinite recursion; they do however have many uses, \emph{e.g.}~as
-%     special markers and delimiters within code.
-%   }
-%   \explpkg{l3seq}{
-%     This implements data-types such as queues and stacks.
-%   }
-%   \explpkg{l3skip}{
-%     Implements the \enquote{rubber length} datatype \texttt{skip}, the
-%     \enquote{rigid length} datatype |dim|, and the math mode
-%     \enquote{rubber length} datatype \texttt{muskip}.
-%   }
-%   \explpkg{l3tl}{
-%     This implements a basic data-type, called a \textit{token-list
-%     variable} (|tl var.|), used for storing named token lists: these are
-%     \TeX{} macros with no arguments.
-%   }
-%   \explpkg{l3token}{
-%     Analysing token lists and token streams, including peeking ahead to
-%     see what's coming next and inspecting tokens to detect which kind
-%     they are.
-%   }
-% \end{description}
+% loads the code now distributed as \pkg{l3kernel}. This monolithic
+% package contains all of the modules regarded by the team as stable,
+% and any changes in this code are very limited. This material is
+% therefore suitable for use in third-party packages without concern
+% about changes in support. All of this code is documented in
+% \texttt{interface3.pdf}.
+%
+% The material in \pkg{l3packages} is also stable, but is not always
+% at a programming level: most notably, \pkg{xparse} is stable and
+% suitable for wider use.
+%
+% Finally, \pkg{l3experimental} contains modules ready for public use
+% but not yet integrated into \pkg{l3kernel}. These modules have to
+% be loaded explicitly. The team anticipate that all of these modules
+% will move to stable status over time, but they may be more flexible
+% in terms of interface and functionality detail. Feedback on these
+% modules is extremely valuable.
 %
 % \section{Moving from \LaTeXe{} to \LaTeX3}
 %