summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3bootstrap.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/l3kernel/l3bootstrap.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3bootstrap.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3bootstrap.dtx575
1 files changed, 575 insertions, 0 deletions
diff --git a/macros/latex/contrib/l3kernel/l3bootstrap.dtx b/macros/latex/contrib/l3kernel/l3bootstrap.dtx
new file mode 100644
index 0000000000..35ab971e15
--- /dev/null
+++ b/macros/latex/contrib/l3kernel/l3bootstrap.dtx
@@ -0,0 +1,575 @@
+% \iffalse meta-comment
+%
+%% File: l3bootstrap.dtx
+%
+% Copyright (C) 2011-2019 The LaTeX3 project
+%
+% It may be distributed and/or modified under the conditions of the
+% LaTeX Project Public License (LPPL), either version 1.3c of this
+% license or (at your option) any later version. The latest version
+% of this license is in the file
+%
+% https://www.latex-project.org/lppl.txt
+%
+% This file is part of the "l3kernel bundle" (The Work in LPPL)
+% and all files in that bundle must be distributed together.
+%
+% -----------------------------------------------------------------------
+%
+% The development version of the bundle can be found at
+%
+% https://github.com/latex3/latex3
+%
+% for those people who are interested.
+%
+%<*driver>
+\documentclass[full,kernel]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \pkg{l3bootstrap} package\\ Bootstrap code^^A
+% }
+%
+% \author{^^A
+% The \LaTeX3 Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released 2019-08-25}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \section{Using the \LaTeX3 modules}
+%
+% The modules documented in \file{source3} are designed to be used on top of
+% \LaTeXe{} and are loaded all as one with the usual |\usepackage{expl3}| or
+% |\RequirePackage{expl3}| instructions. These modules will also form the
+% basis of the \LaTeX3 format, but work in this area is incomplete and not
+% included in this documentation at present.
+%
+% As the modules use a coding syntax different from standard
+% \LaTeXe{} it provides a few functions for setting it up.
+%
+% \begin{function}[updated = 2011-08-13]{\ExplSyntaxOn, \ExplSyntaxOff}
+% \begin{syntax}
+% \cs{ExplSyntaxOn} \meta{code} \cs{ExplSyntaxOff}
+% \end{syntax}
+% The \cs{ExplSyntaxOn} function switches to a category code
+% r\'{e}gime in which spaces are ignored and in which the colon (|:|)
+% and underscore (|_|) are treated as \enquote{letters}, thus allowing
+% access to the names of code functions and variables. Within this
+% environment, |~| is used to input a space. The \cs{ExplSyntaxOff}
+% reverts to the document category code r\'{e}gime.
+% \end{function}
+%
+% \begin{function}[updated = 2017-03-19]
+% {\ProvidesExplPackage, \ProvidesExplClass, \ProvidesExplFile}
+% \begin{syntax}
+% |\RequirePackage{expl3}| \\
+% \cs{ProvidesExplPackage} \Arg{package} \Arg{date} \Arg{version} \Arg{description}
+% \end{syntax}
+% These functions act broadly in the same way as the corresponding
+% \LaTeXe{} kernel
+% functions \tn{ProvidesPackage}, \tn{ProvidesClass} and
+% \tn{ProvidesFile}. However, they also implicitly switch
+% \cs{ExplSyntaxOn} for the remainder of the code with the file. At the
+% end of the file, \cs{ExplSyntaxOff} will be called to reverse this.
+% (This is the same concept as \LaTeXe{} provides in turning on
+% \tn{makeatletter} within package and class code.) The \meta{date} should
+% be given in the format \meta{year}/\meta{month}/\meta{day}. If the
+% \meta{version} is given then it will be prefixed with \texttt{v} in
+% the package identifier line.
+% \end{function}
+%
+% \begin{function}[updated = 2012-06-04]{\GetIdInfo}
+% \begin{syntax}
+% |\RequirePackage{l3bootstrap}|
+% \cs{GetIdInfo} |$Id:| \meta{SVN info field} |$| \Arg{description}
+% \end{syntax}
+% Extracts all information from a SVN field. Spaces are not
+% ignored in these fields. The information pieces are stored in
+% separate control sequences with \cs{ExplFileName} for the part of the
+% file name leading up to the period, \cs{ExplFileDate} for date,
+% \cs{ExplFileVersion} for version and \cs{ExplFileDescription} for the
+% description.
+% \end{function}
+%
+% To summarize: Every single package using this syntax should identify
+% itself using one of the above methods. Special care is taken so that
+% every package or class file loaded with \tn{RequirePackage} or similar
+% are loaded with usual \LaTeXe{} category codes and the \LaTeX3 category code
+% scheme is reloaded when needed afterwards. See implementation for
+% details. If you use the \cs{GetIdInfo} command you can use the
+% information when loading a package with
+% \begin{verbatim}
+% \ProvidesExplPackage{\ExplFileName}
+% {\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
+% \end{verbatim}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3bootstrap} implementation}
+%
+% \begin{macrocode}
+%<*initex|package>
+%<@@=kernel>
+% \end{macrocode}
+%
+% \subsection{Format-specific code}
+%
+% The very first thing to do is to bootstrap the \IniTeX{} system so
+% that everything else will actually work. \TeX{} does not start with
+% some pretty basic character codes set up.
+% \begin{macrocode}
+%<*initex>
+\catcode `\{ = 1 %
+\catcode `\} = 2 %
+\catcode `\# = 6 %
+\catcode `\^ = 7 %
+%</initex>
+% \end{macrocode}
+%
+% Tab characters should not show up in the code, but to be on the
+% safe side.
+% \begin{macrocode}
+%<*initex>
+\catcode `\^^I = 10 %
+%</initex>
+% \end{macrocode}
+%
+% For \LuaTeX{}, the extra primitives need to be enabled. This is not needed
+% in package mode: common formats have the primitives enabled.
+% \begin{macrocode}
+%<*initex>
+\begingroup\expandafter\expandafter\expandafter\endgroup
+\expandafter\ifx\csname directlua\endcsname\relax
+\else
+ \directlua{tex.enableprimitives("", tex.extraprimitives())}%
+\fi
+%</initex>
+% \end{macrocode}
+%
+% Depending on the versions available, the \LaTeX{} format may not have
+% the raw |\Umath| primitive names available. We fix that globally:
+% it should cause no issues. Older \LuaTeX{} versions do not have
+% a pre-built table of the primitive names here so sort one out
+% ourselves. These end up globally-defined but at that is true with
+% a newer format anyway and as they all start |\U| this should be
+% reasonably safe.
+% \begin{macrocode}
+%<*package>
+\begingroup
+ \expandafter\ifx\csname directlua\endcsname\relax
+ \else
+ \directlua{%
+ local i
+ local t = { }
+ for _,i in pairs(tex.extraprimitives("luatex")) do
+ if string.match(i,"^U") then
+ if not string.match(i,"^Uchar$") then %$
+ table.insert(t,i)
+ end
+ end
+ end
+ tex.enableprimitives("", t)
+ }%
+ \fi
+\endgroup
+%</package>
+% \end{macrocode}
+%
+% \subsection{The \tn{pdfstrcmp} primitive in \XeTeX{}}
+%
+% Only \pdfTeX{} has a primitive called \tn{pdfstrcmp}. The \XeTeX{}
+% version is just \tn{strcmp}, so there is some shuffling to do. As
+% this is still a real primitive, using the \pdfTeX{} name is \enquote{safe}.
+% \begin{macrocode}
+\begingroup\expandafter\expandafter\expandafter\endgroup
+ \expandafter\ifx\csname pdfstrcmp\endcsname\relax
+ \let\pdfstrcmp\strcmp
+\fi
+% \end{macrocode}
+%
+% \subsection{Loading support \Lua{} code}
+%
+% When \LuaTeX{} is used there are various pieces of \Lua{} code which need to
+% be loaded. The code itself is defined in \pkg{l3luatex} and is extracted into
+% a separate file. Thus here the task is to load the \Lua{} code both now and
+% (if required) at the start of each job.
+% \begin{macrocode}
+\begingroup\expandafter\expandafter\expandafter\endgroup
+\expandafter\ifx\csname directlua\endcsname\relax
+\else
+ \ifnum\luatexversion<70 %
+ \else
+% \end{macrocode}
+% In package mode a category code table is needed: either use a pre-loaded
+% allocator or provide one using the \LaTeXe{}-based generic code. In format
+% mode the table used here can be hard-coded into the \Lua{}.
+% \begin{macrocode}
+%<*package>
+ \begingroup\expandafter\expandafter\expandafter\endgroup
+ \expandafter\ifx\csname newcatcodetable\endcsname\relax
+ \input{ltluatex}%
+ \fi
+ \newcatcodetable\ucharcat@table
+ \directlua{
+ l3kernel = l3kernel or { }
+ local charcat_table = \number\ucharcat@table\space
+ l3kernel.charcat_table = charcat_table
+ }%
+%</package>
+ \directlua{require("expl3")}%
+% \end{macrocode}
+% As the user might be making a custom format, no assumption is made about
+% matching package mode with only loading the \Lua{} code once. Instead, a
+% query to \Lua{} reveals what mode is in operation.
+% \begin{macrocode}
+ \ifnum 0%
+ \directlua{
+ if status.ini_version then
+ tex.write("1")
+ end
+ }>0 %
+ \everyjob\expandafter{%
+ \the\expandafter\everyjob
+ \csname\detokenize{lua_now:n}\endcsname{require("expl3")}%
+ }%
+ \fi
+ \fi
+\fi
+% \end{macrocode}
+%
+% \subsection{Engine requirements}
+%
+% The code currently requires \eTeX{} and functionality equivalent to
+% \tn{pdfstrcmp}, and also driver and Unicode character support. This is
+% available in a reasonably-wide range of engines.
+% \begin{macrocode}
+\begingroup
+ \def\next{\endgroup}%
+ \def\ShortText{Required primitives not found}%
+ \def\LongText%
+ {%
+ LaTeX3 requires the e-TeX primitives and additional functionality as
+ described in the README file.
+ \LineBreak
+ These are available in the engines\LineBreak
+ - pdfTeX v1.40\LineBreak
+ - XeTeX v0.99992\LineBreak
+ - LuaTeX v0.76\LineBreak
+ - e-(u)pTeX mid-2012\LineBreak
+ or later.\LineBreak
+ \LineBreak
+ }%
+ \ifnum0%
+ \expandafter\ifx\csname pdfstrcmp\endcsname\relax
+ \else
+ \expandafter\ifx\csname pdftexversion\endcsname\relax
+ \expandafter\ifx\csname Ucharcat\endcsname\relax
+ \expandafter\ifx\csname kanjiskip\endcsname\relax
+ \else
+ 1%
+ \fi
+ \else
+ 1%
+ \fi
+ \else
+ \ifnum\pdftexversion<140 \else 1\fi
+ \fi
+ \fi
+ \expandafter\ifx\csname directlua\endcsname\relax
+ \else
+ \ifnum\luatexversion<76 \else 1\fi
+ \fi
+ =0 %
+ \newlinechar`\^^J %
+%<*initex>
+ \def\LineBreak{^^J}%
+ \edef\next
+ {%
+ \errhelp
+ {%
+ \LongText
+ For pdfTeX and XeTeX the '-etex' command-line switch is also
+ needed.\LineBreak
+ \LineBreak
+ Format building will abort!\LineBreak
+ }%
+ \errmessage{\ShortText}%
+ \endgroup
+ \noexpand\end
+ }%
+%</initex>
+%<*package>
+ \def\LineBreak{\noexpand\MessageBreak}%
+ \expandafter\ifx\csname PackageError\endcsname\relax
+ \def\LineBreak{^^J}%
+ \def\PackageError#1#2#3%
+ {%
+ \errhelp{#3}%
+ \errmessage{#1 Error: #2}%
+ }%
+ \fi
+ \edef\next
+ {%
+ \noexpand\PackageError{expl3}{\ShortText}
+ {\LongText Loading of expl3 will abort!}%
+ \endgroup
+ \noexpand\endinput
+ }%
+%</package>
+ \fi
+\next
+% \end{macrocode}
+%
+% \subsection{Extending allocators}
+%
+% In format mode, allocating registers is handled by \pkg{l3alloc}. However, in
+% package mode it's much safer to rely on more general code. For example,
+% the ability to extend \TeX{}'s allocation routine to allow for \eTeX{} has
+% been around since 1997 in the \pkg{etex} package.
+%
+% Loading this support is delayed until here as we are now sure that the
+% \eTeX{} extensions and \tn{pdfstrcmp} or equivalent are available. Thus
+% there is no danger of an \enquote{uncontrolled} error if the engine
+% requirements are not met.
+%
+% For \LaTeXe{} we need to make sure that the extended pool is being used:
+% \pkg{expl3} uses a lot of registers. For formats from 2015 onward there is
+% nothing to do as this is automatic. For older formats, the \pkg{etex}
+% package needs to be loaded to do the job. In that case, some inserts are
+% reserved also as these have to be from the standard pool. Note that
+% \tn{reserveinserts} is \tn{outer} and so is accessed here by csname. In
+% earlier versions, loading \pkg{etex} was done directly and so
+% \tn{reserveinserts} appeared in the code: this then required a \tn{relax}
+% after \tn{RequirePackage} to prevent an error with \enquote{unsafe}
+% definitions as seen for example with \pkg{capoptions}. The optional loading
+% here is done using a group and \tn{ifx} test as we are not quite in the
+% position to have a single name for \tn{pdfstrcmp} just yet.
+% \begin{macrocode}
+%<*package>
+\begingroup
+ \def\@tempa{LaTeX2e}%
+ \def\next{}%
+ \ifx\fmtname\@tempa
+ \expandafter\ifx\csname extrafloats\endcsname\relax
+ \def\next
+ {%
+ \RequirePackage{etex}%
+ \csname reserveinserts\endcsname{32}%
+ }%
+ \fi
+ \fi
+\expandafter\endgroup
+\next
+%</package>
+% \end{macrocode}
+%
+% \subsection{Character data}
+%
+% \TeX{} needs various pieces of data to be set about characters, in particular
+% which ones to treat as letters and which \tn{lccode} values apply as these
+% affect hyphenation. It makes most sense to set this and related information
+% up in one place. Whilst for \LuaTeX{} hyphenation patterns can be read
+% anywhere, other engines have to build them into the format and so we
+% \emph{must} do this set up before reading the patterns. For the Unicode
+% engines, there are shared loaders available to obtain the relevant
+% information directly from the Unicode Consortium data files. These need
+% standard (Ini)\TeX{} category codes and primitive availability and must
+% therefore loaded \emph{very} early. This has a knock-on effect on the
+% $8$-bit set up: it makes sense to do the definitions for those here as
+% well so it is all in one place.
+%
+% For \XeTeX{} and \LuaTeX{}, which are natively Unicode engines, simply
+% load the Unicode data.
+% \begin{macrocode}
+%<*initex>
+\ifdefined\Umathcode
+ \input load-unicode-data %
+ \input load-unicode-math-classes %
+\else
+% \end{macrocode}
+% For the $8$-bit engines a font encoding scheme must be chosen. At present,
+% this is the EC (|T1|) scheme, with the assumption that languages for which
+% this is not appropriate will be used with one of the Unicode engines.
+% \begin{macrocode}
+ \begingroup
+% \end{macrocode}
+% Lower case chars: map to themselves when lower casing and down by |"20| when
+% upper casing. (The characters |a|--|z| are set up correctly by \IniTeX{}.)
+% \begin{macrocode}
+ \def\temp{%
+ \ifnum\count0>\count2 %
+ \else
+ \global\lccode\count0 = \count0 %
+ \global\uccode\count0 = \numexpr\count0 - "20\relax
+ \advance\count0 by 1 %
+ \expandafter\temp
+ \fi
+ }
+ \count0 = "A0 %
+ \count2 = "BC %
+ \temp
+ \count0 = "E0 %
+ \count2 = "FF %
+ \temp
+% \end{macrocode}
+% Upper case chars: map up by |"20| when lower casing, to themselves when upper
+% casing and require an \tn{sfcode} of $999$. (The characters |A|--|Z| are set
+% up correctly by \IniTeX{}.)
+% \begin{macrocode}
+ \def\temp{%
+ \ifnum\count0>\count2 %
+ \else
+ \global\lccode\count0 = \numexpr\count0 + "20\relax
+ \global\uccode\count0 = \count0 %
+ \global\sfcode\count0 = 999 %
+ \advance\count0 by 1 %
+ \expandafter\temp
+ \fi
+ }
+ \count0 = "80 %
+ \count2 = "9C %
+ \temp
+ \count0 = "C0 %
+ \count2 = "DF %
+ \temp
+% \end{macrocode}
+% A few special cases where things are not as one might expect using the above
+% pattern: dotless-I, dotless-J, dotted-I and d-bar.
+% \begin{macrocode}
+ \global\lccode`\^^Y = `\^^Y %
+ \global\uccode`\^^Y = `\I %
+ \global\lccode`\^^Z = `\^^Z %
+ \global\uccode`\^^Y = `\J %
+ \global\lccode"9D = `\i %
+ \global\uccode"9D = "9D %
+ \global\lccode"9E = "9E %
+ \global\uccode"9E = "D0 %
+% \end{macrocode}
+% Allow hyphenation at a zero-width glyph (used to break up ligatures or
+% to place accents between characters).
+% \begin{macrocode}
+ \global\lccode23 = 23 %
+ \endgroup
+\fi
+%</initex>
+% \end{macrocode}
+%
+% \subsection{The \LaTeX3 code environment}
+%
+% The code environment is now set up.
+%
+% \begin{macro}{\ExplSyntaxOff}
+% Before changing any category codes, in package mode we need to save
+% the situation before loading. Note the set up here means that once applied
+% \cs{ExplSyntaxOff} becomes a \enquote{do nothing} command until
+% \cs{ExplSyntaxOn} is used. For format mode, there is no need to save
+% category codes so that step is skipped.
+% \begin{macrocode}
+\protected\def\ExplSyntaxOff{}%
+%<*package>
+\protected\edef\ExplSyntaxOff
+ {%
+ \protected\def\ExplSyntaxOff{}%
+ \catcode 9 = \the\catcode 9\relax
+ \catcode 32 = \the\catcode 32\relax
+ \catcode 34 = \the\catcode 34\relax
+ \catcode 38 = \the\catcode 38\relax
+ \catcode 58 = \the\catcode 58\relax
+ \catcode 94 = \the\catcode 94\relax
+ \catcode 95 = \the\catcode 95\relax
+ \catcode 124 = \the\catcode 124\relax
+ \catcode 126 = \the\catcode 126\relax
+ \endlinechar = \the\endlinechar\relax
+ \chardef\csname\detokenize{l_@@_expl_bool}\endcsname = 0\relax
+ }%
+%</package>
+% \end{macrocode}
+% \end{macro}
+%
+% The code environment is now set up.
+% \begin{macrocode}
+\catcode 9 = 9\relax
+\catcode 32 = 9\relax
+\catcode 34 = 12\relax
+\catcode 38 = 4\relax
+\catcode 58 = 11\relax
+\catcode 94 = 7\relax
+\catcode 95 = 11\relax
+\catcode 124 = 12\relax
+\catcode 126 = 10\relax
+\endlinechar = 32\relax
+% \end{macrocode}
+%
+% \begin{variable}{\l_@@_expl_bool}
+% The status for experimental code syntax: this is on at present.
+% \begin{macrocode}
+\chardef\l_@@_expl_bool = 1\relax
+% \end{macrocode}
+%\end{variable}
+%
+% \begin{macro}{\ExplSyntaxOn}
+% The idea here is that multiple \cs{ExplSyntaxOn} calls are not
+% going to mess up category codes, and that multiple calls to
+% \cs{ExplSyntaxOff} are also not wasting time. Applying
+% \cs{ExplSyntaxOn} alters the definition of \cs{ExplSyntaxOff}
+% and so in package mode this function should not be used until after
+% the end of the loading process!
+% \begin{macrocode}
+\protected \def \ExplSyntaxOn
+ {
+ \bool_if:NF \l_@@_expl_bool
+ {
+ \cs_set_protected:Npx \ExplSyntaxOff
+ {
+ \char_set_catcode:nn { 9 } { \char_value_catcode:n { 9 } }
+ \char_set_catcode:nn { 32 } { \char_value_catcode:n { 32 } }
+ \char_set_catcode:nn { 34 } { \char_value_catcode:n { 34 } }
+ \char_set_catcode:nn { 38 } { \char_value_catcode:n { 38 } }
+ \char_set_catcode:nn { 58 } { \char_value_catcode:n { 58 } }
+ \char_set_catcode:nn { 94 } { \char_value_catcode:n { 94 } }
+ \char_set_catcode:nn { 95 } { \char_value_catcode:n { 95 } }
+ \char_set_catcode:nn { 124 } { \char_value_catcode:n { 124 } }
+ \char_set_catcode:nn { 126 } { \char_value_catcode:n { 126 } }
+ \tex_endlinechar:D =
+ \tex_the:D \tex_endlinechar:D \scan_stop:
+ \bool_set_false:N \l_@@_expl_bool
+ \cs_set_protected:Npn \ExplSyntaxOff { }
+ }
+ }
+ \char_set_catcode_ignore:n { 9 } % tab
+ \char_set_catcode_ignore:n { 32 } % space
+ \char_set_catcode_other:n { 34 } % double quote
+ \char_set_catcode_alignment:n { 38 } % ampersand
+ \char_set_catcode_letter:n { 58 } % colon
+ \char_set_catcode_math_superscript:n { 94 } % circumflex
+ \char_set_catcode_letter:n { 95 } % underscore
+ \char_set_catcode_other:n { 124 } % pipe
+ \char_set_catcode_space:n { 126 } % tilde
+ \tex_endlinechar:D = 32 \scan_stop:
+ \bool_set_true:N \l_@@_expl_bool
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</initex|package>
+% \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex