diff options
author | Karl Berry <karl@freefriends.org> | 2015-04-30 20:40:06 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-04-30 20:40:06 +0000 |
commit | 0c6cb8273aa12c6f87a00617d574be31f19ea1ae (patch) | |
tree | a638979024f3e0c284adcbfe0af37f04fa1a0a7b /Master/texmf-dist/source/latex/l3build | |
parent | 25e26e9a00325030747f024cb884bd6d58f4469b (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/l3build')
-rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 146 |
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 } |