summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-06-25 21:51:46 +0000
committerKarl Berry <karl@freefriends.org>2017-06-25 21:51:46 +0000
commit0baef83f46e61ff1d06c181a1bd8e0df785ff73e (patch)
treeaf33845766e2b07b56e7cd98025bb29edb587a3a /Master/texmf-dist/source/latex/l3build
parenta32eb2dc2cb45c2d6d3713f1f17d183d9e1227a2 (diff)
l3build (25jun17)
git-svn-id: svn://tug.org/texlive/trunk@44698 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx359
1 files changed, 155 insertions, 204 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 815d941b00b..ee9665618c1 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -71,27 +71,28 @@
\luavarset{tdsdir} {distribdir .. "/tds"} {Generated folder where files are organised for a TDS.}
\luavarset{tdsroot} {"latex"}{Root directory of the TDS structure for the bundle/module to be installed into.}
\luavarseparator
-\luavarset{bibfiles} {\{"*.bib"\}}{\BibTeX{} database files.}
-\luavarset{binaryfiles} {\{"*.pdf", "*.zip"\}}
- {Files to be added in binary mode to zip files.}
-\luavarset{bstfiles} {\{"*.bst"\}}{\BibTeX{} style files.}
-\luavarset{checkfiles} {\{~\}}{Extra files unpacked purely for tests}
-\luavarset{checksuppfiles} { }{Files needed for performing regression tests.}
-\luavarset{cmdchkfiles} {\{~\}}{Files need to perform command checking (\cls{l3doc}-based documentation only).}
-\luavarset{cleanfiles} {\{"*.log", "*.pdf", "*.zip"\}}{Files to delete when cleaning.}
-\luavarset{demofiles} {\{~\}}{Files which show how to use a module.}
-\luavarset{docfiles} {\{~\}}{Files which are part of the documentation but should not be typeset.}
-\luavarset{excludefiles} {\{"*\string~"\}} {Files to ignore entirely (default for Emacs backup files).}
-\luavarset{installfiles} {\{"*.sty"\}} {Files to install to the \TeX{} tree and similar tasks.}
-\luavarset{makeindexfiles} {\{"*.ist"\}}{MakeIndex files to be included in a TDS-style zip}
-\luavarset{sourcefiles} {\{"*.dtx", "*.ins"\}}{Files to copy for unpacking.}
-\luavarset{textfiles} {\{"*.md", "*.txt"\}}{Plain text files to send to CTAN as-is.}
-\luavarset{typesetdemofiles}{\{~\}} {Files to typeset before the documentation (as demos), but where the PDF results are not included in the release.}
-\luavarset{typesetfiles} {\{"*.dtx"\}} {Files to typeset for documentation.}
-\luavarset{typesetsuppfiles}{\{~\}} {Files needed to support typesetting when \enquote{sandboxed}.}
-\luavarset{unpackfiles} {\{"*.ins"\}} {Files to run to perform unpacking.}
-\luavarset{unpacksuppfiles} {\{~\}} {Files needed to support unpacking when \enquote{sandboxed}.}
-\luavarset{versionfiles} {\{"*.dtx"\}} {Files for automatic version editing.}
+\luavarset{bibfiles} {\{"*.bib"\}}{\BibTeX{} database files.}
+\luavarset{binaryfiles} {\{"*.pdf", "*.zip"\}}
+ {Files to be added in binary mode to zip files.}
+\luavarset{bstfiles} {\{"*.bst"\}}{\BibTeX{} style files.}
+\luavarset{checkfiles} {\{~\}}{Extra files unpacked purely for tests}
+\luavarset{checksuppfiles} { }{Files needed for performing regression tests.}
+\luavarset{cmdchkfiles} {\{~\}}{Files need to perform command checking (\cls{l3doc}-based documentation only).}
+\luavarset{cleanfiles} {\{"*.log", "*.pdf", "*.zip"\}}{Files to delete when cleaning.}
+\luavarset{demofiles} {\{~\}}{Files which show how to use a module.}
+\luavarset{docfiles} {\{~\}}{Files which are part of the documentation but should not be typeset.}
+\luavarset{excludefiles} {\{"*\string~"\}} {Files to ignore entirely (default for Emacs backup files).}
+\luavarset{installfiles} {\{"*.sty"\}} {Files to install to the \TeX{} tree and similar tasks.}
+\luavarset{makeindexfiles} {\{"*.ist"\}}{MakeIndex files to be included in a TDS-style zip}
+\luavarset{sourcefiles} {\{"*.dtx", "*.ins"\}}{Files to copy for unpacking.}
+\luavarset{textfiles} {\{"*.md", "*.txt"\}}{Plain text files to send to CTAN as-is.}
+\luavarset{typesetdemofiles} {\{~\}} {Files to typeset before the documentation (as demos), but where the PDF results are not included in the release.}
+\luavarset{typesetfiles} {\{"*.dtx"\}} {Files to typeset for documentation.}
+\luavarset{typesetsuppfiles} {\{~\}} {Files needed to support typesetting when \enquote{sandboxed}.}
+\luavarset{typesetsourcefiles}{\{~\}} {Files to copy to unpacking when typesetting.}
+\luavarset{unpackfiles} {\{"*.ins"\}} {Files to run to perform unpacking.}
+\luavarset{unpacksuppfiles} {\{~\}} {Files needed to support unpacking when \enquote{sandboxed}.}
+\luavarset{versionfiles} {\{"*.dtx"\}} {Files for automatic version editing.}
\luavarseparator
\luavarset{bakext} {".bak"} {Extension of backup files.}
\luavarset{dviext} {".dvi"} {Extension of DVI files.}
@@ -202,7 +203,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/06/25}
%
% \maketitle
% \tableofcontents
@@ -440,7 +441,13 @@
% Files that match |typesetsuppfiles| in the |support| directory (|supportdir|) are copied into the |build/local| directory (|localdir|) for the typesetting compilation process.
% Additional dependencies listed in the \var{typesetdeps} variable (empty by default) will also be installed.
%
+% Source files specified in \var{sourcefiles} and \var{typesetsourcefiles}
+% are unpacked before the typesetting takes place. (In most cases
+% \var{typesetsourcefiles} will be mepty, but may be used where there are
+% files to unpack \emph{only} for typesetting.)
+%
% If \var{typesetsearch} is \code{true} (default), standard \texttt{texmf} search trees are used in the typesetting compilation. If set to false, \emph{all} necessary files for compilation must be included in the |build/local| sandbox.
+%
% \end{buildcmd}
%
% \begin{buildcmd}{doc \meta{name(s)}}
@@ -673,9 +680,6 @@
% \end{itemize}
% Modifications made in lines are:
% \begin{itemize}
-% \item Removal of the name of the test file itself.
-% \item Removal of the |pdftex.map| load information given during
-% first page shipout.
% \item Removal spaces at the start of lines.
% \item Removal of |./| at start of file names.
% \item Standardisation of the list of units known to \TeX{} (\pdfTeX{}
@@ -1157,11 +1161,20 @@
% \meta{target} directory.
% \end{function}
%
+% \begin{function}{dirname()}
+% \begin{syntax}
+% |dirname(|\meta{file}|)|
+% \end{syntax}
+% Returns a string comprising the path to a \meta{file} with the name removed
+% (\emph{i.e.}~up to the last |/|). Where the \meta{file} has no path data,
+% |"."| is returned.
+% \end{function}
+%
% \begin{function}{basename()}
% \begin{syntax}
% |basename(|\meta{file}|)|
% \end{syntax}
-% Returns a string comprising the full name of the file with the
+% Returns a string comprising the full name of the \meta{file} with the
% path removed (\emph{i.e.}~from the last |/| onward).
% \end{function}
%
@@ -1243,6 +1256,14 @@
% error level.
% \end{function}
%
+% \begin{function}{spltpath()}
+% \begin{syntax}
+% |splitpath(|\meta{file}|)|
+% \end{syntax}
+% Returns two strings split at the last |/|: the \texttt{dirname()} and
+% the |basename()|.
+% \end{function}
+%
% \begin{function}{unix_to_win()}
% \begin{syntax}
% |unix_to_win(|\meta{path}|)|
@@ -1312,21 +1333,33 @@
%
% \subsection{Preliminaries}
%
-% Unlike in the \LaTeXe{} regression test suite, reset catcodes: each test should set these
-% as appropriate. There's also a quick test for Con\TeX{}t: it defines |\unprotect|
-% which should be a reasonable marker (and is needed as some catcodes are otherwise
-% wrong).
+% We require \eTeX{}.
+% \begin{macrocode}
+\begingroup\expandafter\expandafter\expandafter\endgroup
+\expandafter\ifx\csname eTeXversion\endcsname\relax
+ \errmessage{e-TeX is required to use regression-test.tex}%
+ \expandafter\endinput
+\fi
+% \end{macrocode}
+%
+% \begin{macro}{\reset@catcodes}
+% Unlike in the \LaTeXe{} regression test suite, reset catcodes: each test
+% should set these as appropriate. There's also a quick test for Con\TeX{}t:
+% it defines |\unprotect| which should be a reasonable marker (and is
+% needed as some catcodes are otherwise wrong).
% \begin{macrocode}
\ifx\unprotect\undefined
\expandafter\edef\csname reset\string @catcodes\endcsname{%
\catcode`\noexpand\@=\the\catcode`\@\relax
- }
+ }%
\catcode`\@=11 %
\else
\unprotect
\def\reset@catcodes{\protect}%
\fi
% \end{macrocode}
+% \end{macro}
+%
% Put \TeX{} into scroll mode, and stop it showing the
% implementation details of macros in error messages.
% \begin{macrocode}
@@ -1341,24 +1374,30 @@
\showboxdepth=\maxdimen
% \end{macrocode}
%
-% The |\showoutput| command of \LaTeX{} calls |\loggingoutput| which in
-% turn calls |\errorstopmode| but we want to continue running without
-% any stops.
+% \begin{macro}{\logginoutput}
+% The |\showoutput| command of \LaTeX{} calls |\loggingoutput| which in turn
+% calls |\errorstopmode| but we want to continue running without any stops.
% \begin{macrocode}
-\def\loggingoutput{\tracingoutput1
- \showboxbreadth\maxdimen\showboxdepth\maxdimen}
+\def\loggingoutput{%
+ \tracingoutput=1 %
+ \showboxbreadth=\maxdimen
+ \showboxdepth=\maxdimen
+}
% \end{macrocode}
+% \end{macro}
%
-% Set the newline character: \LaTeXe{} does this but plain-based formats
-% do not.
+% Set the newline character: \LaTeXe{} does this but plain-based formats do
+% not.
% \begin{macrocode}
\newlinechar=`\^^J
% \end{macrocode}
%
% \subsection{Commands in test files}
%
-% A long version of |\typeout|, because tests may contain |\par| tokens.
-% Besides, with that |\TYPE|, we can do |\TYPE { ... \TRUE ... \NEWLINE ... }|.
+% \begin{macro}{\LONGTYPEOUT, \TYPE}
+% A long version of |\typeout|, because tests may contain |\par| tokens.
+% Besides, with that |\TYPE|, we can do
+% |\TYPE { ... \TRUE ... \NEWLINE ... }|.
% \begin{macrocode}
\long\def\LONGTYPEOUT#1{%
\begingroup
@@ -1369,48 +1408,24 @@
\let\TYPE\LONGTYPEOUT
% \end{macrocode}
%
-% Start the test, after the optional |\documentclass|
-% |\begin{document}| commands with |\START|. All lines in the |.log| file
-% before this will be ignored.
-%
-% It also prints a DocStrip-style
-% character table in the |.tlg| file.
-% Is this necessary any more? Probably too late to remove it.
+% \begin{macro}{\STARTMESSAGE, \START}
+% Start the test, after the optional |\documentclass|
+% |\begin{document}| commands with |\START|. All lines in the |.log| file
+% before this will be ignored.
% \begin{macrocode}
\def\STARTMESSAGE{This is a generated file for the l3build validation system.}
-\def\START{\LONGTYPEOUT{^^JSTART-TEST-LOG^^J^^J%
- \STARTMESSAGE%
-^^J^^JDon't change this file in any respect.%
-^^J^^J}}
-\begingroup
-\catcode`\^^\=0
-\catcode`\^^A=\catcode`\%
-^^\catcode`^^\ =11
-^^\catcode`^^\%=11
-^^\catcode`^^\#=11
-^^\catcode`^^\~=11
-^^\endlinechar=`^^\^^J
-^^\catcode`^^\\=11^^A
-^^\gdef^^\CTable{
-%% \CharacterTable
-%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
-%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
-%% Digits \0\1\2\3\4\5\6\7\8\9
-%% Exclamation \! Double quote \" Hash (number) \#
-%% Dollar \$ Percent \% Ampersand \&
-%% Acute accent \' Left paren \( Right paren \)
-%% Asterisk \* Plus \+ Comma \,
-%% Minus \- Point \. Solidus \/
-%% Colon \: Semicolon \; Less than \<
-%% Equals \= Greater than \> Question mark \?
-%% Commercial at \@ Left bracket \[ Backslash \\
-%% Right bracket \] Circumflex \^ Underscore \_
-%% Grave accent \` Left brace \{ Vertical bar \|
-%% Right brace \} Tilde \~}
-%%
-}^^A
-^^\endgroup{}%
+\def\START{%
+ \LONGTYPEOUT{^^JSTART-TEST-LOG^^J}%
+ \LONGTYPEOUT{^^J%
+ \STARTMESSAGE%
+ ^^J^^JDon't change this file in any respect.%
+ ^^J^^J%
+ }%
+}
% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@@end, \END}
% The test should end with |\END| or |\end{document}|
% or |\bye| in plain \TeX{}.
% \begin{macrocode}
@@ -1419,168 +1434,87 @@
\else
\let\@@@end\@@end
\fi
-\def\END
- {%
- \ifx\currentiflevel\@undefined\else
- \ifnum\currentgrouplevel>0 %
- \LONGTYPEOUT{Bad grouping: \the\currentgrouplevel!}%
- \fi
- \ifnum\currentiflevel>2 %
- \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-2!}%
- \fi
- \fi
- \LONGTYPEOUT{^^JEND-TEST-LOG^^J}\@@@end
- }
+\def\END{%
+ \ifnum\currentgrouplevel>0 %
+ \LONGTYPEOUT{Bad grouping: \the\currentgrouplevel!}%
+ \fi
+ \ifnum\currentiflevel>2 %
+ \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-2!}%
+ \fi
+ \LONGTYPEOUT{^^JEND-TEST-LOG^^J}%
+ \@@@end
+}
\ifx\@@end\@undefined
\let\end\END
\else
\let\@@end\END
\fi
% \end{macrocode}
-% After the |\START| should come declarations of the format and style
-% options being used.
-% \begin{macrocode}
-\def\FORMAT#1{\LONGTYPEOUT{Format: #1}%
- \def\@tempa{#1}\ifx\@tempa\@EJ\else
- \OMIT\TYPE{WARNING: Declared format #1,^^JActual format \@EJ}\TIMO\fi}
-% \end{macrocode}
-% The old version got this information from everyjob,
-% but that does not work with \LaTeXe\ as |\everyjob| is cleared.
-% \begin{macrocode}
-\edef\@EJ{\fmtname <\fmtversion>}
-% \end{macrocode}
-% Some author info:
-% \begin{macrocode}
-\def\AUTHOR#1{\LONGTYPEOUT{Author: #1}}
-% \end{macrocode}
-% Surround commands which produce irrelevant lines in the .log file by
-% |\OMIT|\dots|\TIMO|
+% \end{macro}
+%
+% \begin{macro}{\OMIT, \TIMO}
+% Surround commands which produce irrelevant lines in the |.log| file by
+% |\OMIT|\dots|\TIMO|
% \begin{macrocode}
\def\OMIT{\LONGTYPEOUT{OMIT}}
\def\TIMO{\LONGTYPEOUT{TIMO}}
% \end{macrocode}
-% Not all packages declare themselves to the log file, and we can not
-% rely on TeX`s output as it includes full path names, and does not
-% include version numbers etc.
-%
-% If the class or package is loaded with options, you may
-% specify the options in the |\CLASS| (|\PACKAGE|) declaration. eg:
-% \begin{verbatim}
-% \CLASS[german,a4page]{article v2.0 1994/01/02}
-% \PACKAGE{ifthen v2.2 1993/11/12}
-% \PACKAGE[dvips]{graphics v 3.8 1994/02/02}
-% \end{verbatim}
-% \begin{macrocode}
-\def\CLASS{\@ifnextchar[\OPTCLASS\XCLASS}
-\def\OPTCLASS[#1]#2{%
- \TYPE{Main Class: #2^^J\space\space\space\space Options: #1}}
-\def\XCLASS#1{%
- \TYPE{Main Class: #1}}
-\def\PACKAGE{\@ifnextchar[\OPTPACKAGE\XPACKAGE}
-\def\OPTPACKAGE[#1]#2{%
- \TYPE{Package: #2^^J\space\space\space\space Options: #1}}
-\def\XPACKAGE#1{%
- \TYPE{Package: #1}}
-% \end{macrocode}
+% \end{macro}
%
-% The commands above require 2e's \verb|\@ifnextchar|, so copy that definition verbatim if necessary:
-% \begin{macrocode}
-\ifx\@ifnextchar\@undefined
-\long\def\@ifnextchar#1#2#3{%
- \let\reserved@d=#1%
- \def\reserved@a{#2}%
- \def\reserved@b{#3}%
- \futurelet\@let@token\@ifnch}
-\def\@ifnch{%
- \ifx\@let@token\@sptoken
- \let\reserved@c\@xifnch
- \else
- \ifx\@let@token\reserved@d
- \let\reserved@c\reserved@a
- \else
- \let\reserved@c\reserved@b
- \fi
- \fi
- \reserved@c}
-\def\:{\let\@sptoken= } \: % this makes \@sptoken a space token
-\def\:{\@xifnch} \expandafter\def\: {\futurelet\@let@token\@ifnch}
-\fi
-% \end{macrocode}
-% After the above declarations, and before the main tests, you may
-% optionally declare' all the commands in the `module' that you are
-% about to test. These commands will be registered as defined,
-% undefined or relaxed (i.e.~|\let| to |\relax|). You may wish to declare
-% commands not currently implemented, so that if they are added at a
-% later stage, the test will fail, reminding someone to document the
-% fact that the user interface has changed.
-% \begin{macrocode}
-\def\CHECKCOMMAND#1{%
- \ifx#1\@undefined\LONGTYPEOUT{Undefined \string#1}\else
- \ifx#1\relax\LONGTYPEOUT{Relaxed \space\space\string#1}\else
- \LONGTYPEOUT{Defined \space\space\string#1}\fi\fi}
-% \end{macrocode}
% To allow testing of possible changes, we allow extra code to be read
% in before the test starts. The necessary code should be placed in a
% file |regression-test.cfg|.
% \begin{macrocode}
\ifx\InputIfFileExists\@undefined
-\newread\@inputcheck
-\long\def\InputIfFileExists#1#2#3{%
- \openin\@inputcheck#1\relax
- \ifeof\@inputcheck
- \def\reserved@a{#3}%
- \else
- \def\reserved@a{#2\input #1\relax}%
- \fi
- \closein\@inputcheck
- \reserved@a}
+ \newread\@inputcheck
+ \long\def\InputIfFileExists#1#2#3{%
+ \openin\@inputcheck#1\relax
+ \ifeof\@inputcheck
+ \def\reserved@a{#3}%
+ \else
+ \def\reserved@a{#2\input #1\relax}%
+ \fi
+ \closein\@inputcheck
+ \reserved@a
+ }%
\fi
\InputIfFileExists{regression-test.cfg}
- {\LONGTYPEOUT{^^J***^^Jregression-test.cfg in operation^^J***^^J}}{}
-% \end{macrocode}
-%
-% Load the map file early so it does not appear in the log.
-% \begin{macrocode}
-\ifdefined\pdfoutput
- \ifnum\pdfoutput>0 %
- \pdfmapfile{pdftex.map}%
- \fi
-\else
- \ifdefined\outputmode
- \ifnum\outputmode>0 %
- \pdfextension mapfile{pdftex.map}%
- \fi
- \fi
-\fi
+ {\LONGTYPEOUT{^^J***^^Jregression-test.cfg in operation^^J***^^J}}{}
% \end{macrocode}
%
% \subsection{Formatting the \texttt{.log} file}
%
-% We are not starved for space in the log file output, so let's make it as
-% verbose as is useful when reading the |.diff|'s.
+% \begin{macro}{\gTESTint}
+% For tracking the total number of tests.
+% \begin{macrocode}
+\newcount\gTESTint
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}
+% {\SEPARATOR, \TEST, \TESTEXP, \TRUE, \FALSE, \YES, \NO, \NEWLINE}
+% We are not starved for space in the log file output, so let's make it as
+% verbose as is useful when reading the |.diff|'s.
% \begin{macrocode}
-\newcount \gTESTint
\def\SEPARATOR{%
\TYPE{%
============================================================%
}%
}
-% \end{macrocode}
-% \begin{macrocode}
\long\def\TEST#1#2{%
- \advance \gTESTint 1 %
+ \global\advance\gTESTint by 1 %
\SEPARATOR
- \LONGTYPEOUT{%
- TEST \the\gTESTint: \detokenize{#1}}%
+ \LONGTYPEOUT{TEST \the\gTESTint: \detokenize{#1}}%
\SEPARATOR
\begingroup
\let\TYPE\LONGTYPEOUT
#2%
\endgroup
- \SEPARATOR \LONGTYPEOUT{}%
+ \SEPARATOR
+ \LONGTYPEOUT{}%
}
\long\def\TESTEXP#1#2{%
- \advance \gTESTint 1 %
+ \global\advance\gTESTint by 1 %
\SEPARATOR
\LONGTYPEOUT{%
TEST \the\gTESTint: \detokenize{#1}}%
@@ -1598,9 +1532,26 @@
\def \NO {\TYPE{NO}}
\def \NEWLINE {\TYPE{^^J}}
% \end{macrocode}
+% \end{macro}
%
% \subsection{Suppressing variable data in output}
%
+% Load the map file early so it does not appear in the log.
+% \begin{macrocode}
+\ifx\pdfoutput\@undefined
+ \ifx\outputmode\@undefined
+ \else
+ \ifnum\outputmode>0 %
+ \pdfextension mapfile{pdftex.map}%
+ \fi
+ \fi
+\else
+ \ifnum\pdfoutput>0 %
+ \pdfmapfile{pdftex.map}%
+ \fi
+\fi
+% \end{macrocode}
+%
% To make any PDF file produced comparable we need to suppress various
% pieces of data. This works in concert with setting the epoch from the
% environment side (as not all output can be controlled here). We are