summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-04-30 20:40:06 +0000
committerKarl Berry <karl@freefriends.org>2015-04-30 20:40:06 +0000
commit0c6cb8273aa12c6f87a00617d574be31f19ea1ae (patch)
treea638979024f3e0c284adcbfe0af37f04fa1a0a7b /Master/texmf-dist/source/latex
parent25e26e9a00325030747f024cb884bd6d58f4469b (diff)
l3build (30apr15)
git-svn-id: svn://tug.org/texlive/trunk@37132 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx146
1 files changed, 108 insertions, 38 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 9ac009cddf5..f3fae6b0e79 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -39,8 +39,8 @@
\RequirePackage{expl3}
\def\ExplFileName{l3build}
\def\ExplFileDescription{L3 Regression test suite}
-\def\ExplFileDate{2015/04/02}
-\def\ExplFileVersion{5564}
+\def\ExplFileDate{2015/04/30}
+\def\ExplFileVersion{5602}
\documentclass[full]{l3doc}
\renewcommand\partname{Part}
\usepackage{multicol,needspace}
@@ -92,10 +92,10 @@
\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{auxfiles} {\{"*.aux", "*.toc"\}}
- {Auxiliary typesetting files that should be auto-removed.}
+\luavarset{bibfiles} {\{"*.bst"\}}{\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).}
@@ -141,6 +141,14 @@
\luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
\luavarset{indexstyle} {"gind.ist"}{MakeIndex style for index creation}
\luavarseparator
+\luavarseparator
+\luavarset{biberexe} {"biber"} {Biber executable}
+\luavarset{biberopts} {""} {Biber options}
+\luavarset{bibtexexe} {"bibtex8"} {\BibTeX{} executable}
+\luavarset{bibtexopts} {"-W"} {\BibTeX{} options}
+\luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
+\luavarset{makeindexopts}{""} {MakeIndex options}
+\luavarseparator
\luavarset{checkruns} {1} {How many times to run a check file before comparing the log.}
\luavarset{packtdszip} {false} {Build a TDS-style zip file for CTAN?}
\luavarset{scriptname} {"build.lua"} {Name of script used in dependencies.}
@@ -372,15 +380,18 @@
% The `root' of the TDS structure is defined by \var{tdsroot}, which is \luavar{tdsroot} by default. Plain users would redefine this to |"plain"| (or perhaps |"generic"|), for example.
% The build process for a |.tds.zip| file currently assumes a `standard'
% structure in which all extracted files should be places inside the |tex|
-% tree in a single directory, as shown above.
+% tree in a single directory, as shown above. If the module includes any
+% \BibTeX{} or MakeIndex styles these will be placed in the appropriate
+% subtrees.
%
% \pagebreak[2]
% The |doc| tree is constructed from:
% \begin{itemize}
-% \item all files matched by \var{demofiles}, and
+% \item all files matched by \var{demofiles},
% \item all files matched by \var{typesetfiles} with their extension replaced with |.pdf|,
-% \item all files matched by \var{textfiles}, and
-% \item all files matched by \var{readmefiles}, but when copied their extension is entirely removed (e.g., |README.markdown| is copied as just |README|).
+% \item all files matched by \var{textfiles},
+% \item all files matched by \var{readmefiles}, but when copied their extension is entirely removed (e.g., |README.markdown| is copied as just |README|), and
+% \item all files matched by \var{bibfiles}.
% \end{itemize}
% The |source| tree is constructed from all files matched by \var{typesetfiles} and \var{sourcefiles}.
% The |tex| tree from all files matched by \var{installfiles}.
@@ -389,8 +400,6 @@
%
% Binary files should be specified with the \var{binaryfiles} variable (default \luavar{binaryfiles}); these are added to the zip archive without normalising line endings (text files are automatically converted to Unix-style line endings).
%
-% Any auxiliary files in the working directory may interfere with the automatic typesetting process. Those listed in \var{auxfiles} are automatically removed to prevent this, and are also deleted by the |clean| operation. (This seetting is most useful when typesetting manually and automatically may use different settings, for example enabling/disabling \pkg{hyperref}.)
-%
% To create the archive, by default the binary \var{zipexe} is used (\luavar{zipexe}) with options \var{zipopts} (|-v -r -X|). The intermediate build directories \var{ctandir} and \var{tdsdir} are used to construct the archive.
% \end{buildcmd}
%
@@ -573,47 +582,53 @@
% To allow test files to be used between different systems (\emph{e.g.}~when
% multiple developers are involved in a project), the log files are normalised
% before comparison during checking. This removes some system-dependent
-% data but also some variations due to different engines and bugs in some
-% versions of some engines. This normalisation consists of two parts: removing
-% (\enquote{ignoring}) some lines and modifying others to give consistent
-% test. Currently, the following types of line are ignored:
+% data but also some variations due to different engines. This normalisation
+% consists of two parts: removing (\enquote{ignoring}) some lines and modifying
+% others to give consistent test. Currently, the following types of line are
+% ignored:
% \begin{itemize}
% \item Lines before the \cs{START}, after the \cs{END} and within
% \cs{OMIT}/\cs{TIMO} blocks
% \item Entirely blank lines, including those consisting only of spaces.
-% \item Lines containing file dates in the
-% \texttt{\meta{yyyy}/\meta{mm}/\meta{dd}} format.
+% \item Lines containing file dates in format
+% \texttt{\meta{yyyy}/\meta{mm}/\meta{dd}}.
% \item Lines starting \cs{openin} or \cs{openout}.
-% \item \LuaTeX{}-specific lines in box output for the \cs{local\ldots}
-% concepts it introduces when these are set to their defaults.
-% \item \LuaTeX{}-specific lines in box output which record
-% \cs{discretionary}.
% \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 (deals with some issues
-% with \LuaTeX{} using a different amount of indentation to other engines).
+% \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{}
% and \LuaTeX{} add a small number of additional units which are not
-% known to \XeTeX{}).
+% known to \TeX90 or \XeTeX{}).
% \item Standardisation of \verb*|\csname\endcsname | to |\csname\endcsname|
% (the former is formally correct, but the latter was produced for many
% years due to a \TeX{} bug).
% \item Conversion of \texttt{on line \meta{number}} to \texttt{on line ...}
% to allow flexibility in changes to test files.
-% \item Restriction of glue set in boxes to four decimal places (\LuaTeX{}
-% may vary in the last digit from the \pdfTeX{} values).
-% \item Removal of the \texttt{display} added by \TeX{} versions other than
-% \LuaTeX{} to display math boxes.
-% \item Removal of the Omega-like \texttt{direction TLT} added by
-% \LuaTeX{} to boxes running in the \enquote{normal} way.
-% \item Conversion of low chars ($1$ to $31$) to |^^| notation (\LuaTeX{}
-% does not do this).
-% \item Correction of a \LuaTeX{} error message typo (|I''m going to assume|).
+% \item
+% \end{itemize}
+%
+% \LuaTeX{} makes several additional changes to the log file. As normalising
+% these may not be desirable in all cases, they are handled separately.
+% When creating \LuaTeX{}-specific test files (either with \LuaTeX{} as
+% the standard engine or saving a \LuaTeX{}-specific |.tlg| file) no futher
+% normalisation is undertaken. On the other hand, for cross-engine comparision
+% the following normalisation is applied:
+% \begin{itemize}
+% \item Removal of additional (unused) |\discretionary| points.
+% \item Removal of |U+...| notation for missing characters.
+% \item Removal of |display| for display math boxes
+% (included by \TeX90/\pdfTeX{}/\XeTeX).
+% \item Removal of Omega-like |direction TLT| information.
+% \item Removal of additional whatsit containing local paragraph information
+% (|\localinterlinepenalty|, \emph{etc.}).
+% \item Rounding of glue set to four decimal places (glue set may be
+% slightly different in \LuaTeX{} compared to other engines).
+% \item Conversion of low chars ($1$ to $31$) to |^^| notation.
% \end{itemize}
%
% \subsection{Generating test files with \pkg{DocStrip}}
@@ -819,8 +834,61 @@
% \label{fig:box-log}
% \end{figure}
%
+% \subsection{Typesetting documentation}
+%
+% As part of the overall build process, \pkg{l3build} will create PDF
+% documentation as described earlier. The standard build process for PDFs
+% will attempt to run Biber, \BibTeX{} and MakeIndex as appropriate
+% (the exact binaries used are defined by \luavar{biberexe}, \luavar{bibtexexe}
+% and \luavar{makeindexexe}). However, there is no attempt to create an entire
+% PDF creation system in the style of \texttt{latexmk} or similar.
+%
+% For package authors who have more complex requirements than those covered
+% by the standard set up, the Lua script offers the possibility for
+% customisation. The Lua function \texttt{typeset} may be defined before
+% reading \texttt{l3build.lua} and should take one argument, the name of
+% the file to be typeset. Within this function, the auxiliary Lua
+% functions \texttt{biber}, \texttt{bibtex}, \texttt{makeindex} and
+% \texttt{tex} can be used, along with custom code, to define a PDF
+% typesetting pathway. The functions \texttt{biber} and \texttt{bibtex}
+% take a single argument: the name of the file to work with \emph{minus}
+% any extension. The \texttt{tex} takes as an arugment the full name
+% of the file. The most complex function \texttt{makeindex} requires the
+% name, input extension, putput extension, log extension and style name.
+% For example, Figure~\ref{fig:PDF} shows a simple script which might
+% apply to a case where multiple \BibTeX{} runs are needed (perhaps where
+% citations can appear within other references).
+%
+% \begin{figure}[!b]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% #!/usr/bin/env texlua
%
+% -- Build script with custom PDF route
+%
+% module = "mymodule"
+%
+% function typeset (file)
+% local name = string.match (file, "^(.*)%.") or name
+% local errorlevel = tex (file)
+% if errorlevel == 0 then
+% -- Return a non-zero errorlevel if anything goes wrong
+% errorlevel = (
+% bibtex (name) +
+% tex (file) +
+% bibtex (name) +
+% tex (file) +
+% tex (file)
+% )
+% end
+% return errorlevel
+% end
%
+% kpse.set_program_name("kpsewhich")
+% dofile(kpse.lookup("l3build.lua"))
+% \end{lstlisting}
+% \caption{A customised PDF creation script.}
+% \label{fig:PDF}
+% \end{figure}
%
% \end{documentation}
%
@@ -841,7 +909,7 @@
% Unlike in the \LaTeXe{} regression test suite, reset catcodes: each test should set these
% as appropriate.
% \begin{macrocode}
-\expandafter\edef\csname\detokenize{reset@catcodes}\endcsname{%
+\expandafter\edef\csname reset\string @catcodes\endcsname{%
\catcode`\noexpand\@=\the\catcode`\@\relax
}
\catcode`\@=11 %
@@ -940,11 +1008,13 @@
\fi
\def\END
{%
- \ifnum\currentgrouplevel>0 %
- \LONGTYPEOUT{Bad grouping: \the\currentgrouplevel!}%
- \fi
- \ifnum\currentiflevel>1 %
- \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-1!}%
+ \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{END-TEST-LOG}\@@@end
}