diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/base/latexrelease.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/base/latexrelease.dtx | 483 |
1 files changed, 483 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/base/latexrelease.dtx b/Master/texmf-dist/source/latex/base/latexrelease.dtx new file mode 100644 index 00000000000..21e5cc909c3 --- /dev/null +++ b/Master/texmf-dist/source/latex/base/latexrelease.dtx @@ -0,0 +1,483 @@ +% \iffalse meta-comment +% +% Copyright 1993-2015 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% It may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% +% \iffalse +% +%<*dtx> + \ProvidesFile{latexrelease.dtx} +%</dtx> +%<driver>\ProvidesFile{latexrelease.drv} +%<fixltx2e>\ProvidesPackage{fixltx2e} +%<latexrelease>\ProvidesPackage{latexrelease} +% \fi +% \ProvidesFile{latexrelease.dtx} +%<fixltx2e> [2015/02/21 v2.0a fixes to LaTeX (obsolete)] +%<!fixltx2e> [2015/02/21 v1.0c LaTeX release emulation and tests] +% +% \iffalse +%<*driver> + \documentclass{ltxdoc} + \newcommand\Lopt[1]{\textsf{#1}} + \let\Lpack\Lopt + \providecommand{\file}[1]{\texttt{#1}} + \providecommand{\MF}{\textsf{Metafont}} + \providecommand{\danger}{\marginpar[\hfill\protect\Huge!!]{\protect\Huge!!\hfill}} + \begin{document} + \DocInput{latexrelease.dtx} + \end{document} +%</driver> +% \fi +% +% \CheckSum{100} +% +% +% \let\package\textsf +% +% +% \GetFileInfo{latexrelease.dtx} +% +% \title{The \Lpack{latexrelease} package\thanks{This file +% has version number \fileversion, last +% revised \filedate.}} +% \author{The \LaTeX3 Project} +% \date{\filedate} +% \MaintainedByLaTeXTeam{latex} +% \maketitle +% +% \section{Introduction} +% Prior to the 2015 release of \LaTeX{}, essentially no changes had been +% made to the \LaTeX\ format code for some years, with all +% improvements being instead added to the package \Lpack{fixltx2e}. +% +% While this worked at a technical level it meant that you had to +% explicitly opt-in to bug fixes and improvements, and the vast +% majority of documents did not benefit. +% +% As described in \LaTeX\ News 22, a new policy is being implemented +% in which improvements will now be added to the format by default, +% and this \Lpack{latexrelease} package may be used to ensure +% stability where needed, either by making a new format use an older +% definition of some commands, or conversely may be used to supply the +% new definitions for use with an old format. +% +% The basic use is: +%\begin{verbatim} +% \RequirePackage[2015/01/01]{latexrelease} +% \documentclass{article} +% .... +%\end{verbatim} +% +% After such a declaration the document will use definitions current +% in the January 2015 \LaTeX{}, whether the actual format being used is +% older, or newer than that date. In the former case a copy of +% |latexrelease.sty| would need to be made available for use with the +% older format. This may be used, for example, to share a document +% between co-workers using different \LaTeX\ releases, or to protect a +% document from being affected by system updates. As well as the +% definitions within the format itself, individual packages may use +% the commands defined here to adjust their definitions to the +% specified date as described below. +% +% +% The bulk of this package, after some initial setup and option +% handling consists of a series of |\IncludeInRelease| commands +% which have been extracted from the main source files of the \LaTeX\ +% format. These contain the old and new versions of any commands with +% modified definitions. +% +% \section{Package Options} +% \begin{itemize} +% \item \emph{yyyy/mm/dd} +% The package accepts any \LaTeX\ format date as argument,% +% although dates in the future for which the current release of this +% package has no information will generate a warning. +% +% \item% +% |current| This is the default behaviour, it does not change the +% effective date of the format but does ensure that the +% |\IncludeInRelease| command is defined. +% +% \item +% |latest| sets the effective date of the format to the release date +% of this file, so in an older format applies all patches currently +% available. +% \end{itemize} +% +% +% \section{Release Specific Code} +% +% The |\IncludeInRelease| mechanism allows the kernel developer to +% associate code with a specific date to choose different versions of +% definitions depending on the date specified as an option to the +% \Lpack{latexrelease} package. Is also available for use by package +% authors (or even in a document if necessary). +% +% \medskip +% +% \noindent\DescribeMacro{\IncludeInRelease} +% \marg{code-date}^^A +% \oarg{format-date}%^^A +% \marg{label}^^A +% \marg{message}^^A +% \meta{code}^^A +% |\EndIncludeInRelease| +% +% \begin{description} +% +% \item[\marg{code-date}] This date is associated with the \marg{code} +% argument and will be compared to the requested date in the option to +% the \Lpack{latexrelease}. +% +% \item[\oarg{format-date}] This optional argument can be used to +% specify a format date with the code in addition to the mandatory +% \marg{code-date} argument. This can be useful for package developers +% as described below. +% +% \item[\marg{label}] The \marg{label} argument is an identifier +% (string) that within a given package must be a unique label for each +% related set of optional definitions. Per package at most one code +% block from all the |\IncludeInRelease| declarations with the same +% label will be executed. +% +% \item[\marg{message}] +% The \marg{message} is an informative string that is used in +% messages. It has no other function. +% +% \item[\meta{code}] +% Any \TeX\ code after the |\IncludeInRelease| arguments +% up until the and the following |\EndIncludeInRelease| +% is to be +% conditionally included depending on the date of the format as +% described below. +% +% \end{description} +% +% The |\IncludeInRelease| declarations with a given label should be in +% reverse chronological order in the file. The one chosen will depend +% on this order, the effective format version and the date options, as +% described below. +% +% If your package \Lpack{mypackage} defines a |\widget| command but +% has one definition using the features available in the 2015 \LaTeX\ +% release, and a different definition is required for older formats +% then you can use: +%\begin{verbatim} +% \IncludeInRelease{2015/01/01}{\widget}{Widget Definition} +% \def\widget{new version}% +% \EndIncludeInRelease +% +% \IncludeInRelease{0000/00/00}{\widget}{Widget Definition} +% \def\widget{old version}% +% \EndIncludeInRelease +%\end{verbatim} +% +% If a document using this package is used with a format with +% effective release date of 2015/01/01 or later the new code will be +% used, otherwise the old code will be used. Note the \emph{effective +% release date} might be the original \LaTeX\ release date as shown at +% the start of every \LaTeX\ job, or it may be set by the +% \Lpack{latexrelease} package, so for example a document author who +% wants to ensure the new version is used could use +%\begin{verbatim} +% \RequirePackage[2015/01/01]{latexrelease} +% \documentclass{article} +% \usepackage{mypackage} +%\end{verbatim} +% +% If the document is used with a \LaTeX\ format from 2014 or before, +% then \Lpack{latexrelease} will not have been part of the original +% distribution, but it may be obtained from a later \LaTeX\ release or +% from CTAN and distributed with the document, it will make an older +% \LaTeX\ release act essentially like the 2015 release. +% +% \subsection{Intermediate Package Releases} +% +% The above example works well for testing against the latex format +% but is not always ideal for controlling code by the release date of +% the \emph{package}. Suppose \LaTeX\ is not updated but in March you +% update the \Lpack{mypackage} package and modify the definition of +% |\widget|. You could code the package as: +%\begin{verbatim} +% \IncludeInRelease{2015/03/01}{\widget}{Widget Definition} +% \def\widget{even newer improved March version}% +% \EndIncludeInRelease +% +% \IncludeInRelease{2015/01/01}{\widget}{Widget Definition} +% \def\widget{new version}% +% \EndIncludeInRelease +% +% \IncludeInRelease{0000/00/00}{\widget}{Widget Definition} +% \def\widget{old version}% +% \EndIncludeInRelease +%\end{verbatim} +% +% This would work and allow a document author to choose a date such as +%\begin{verbatim} +% \RequirePackage[2015/03/01]{latexrelease} +% \documentclass{article} +% \usepackage{mypackage} +%\end{verbatim} +% +% To use the latest version, however it would have disadvantage that +% until the next release of \LaTeX, by default, if the document does +% not use \Lpack{latexrelease} to specify a date, the new improved +% code will not be selected as the effective date will be 2015/01/01 +% and so the first code block will be skipped. +% +% For this reason |\IncludeInRelease| has an optional argument that +% specifies an alternative date to use if a date option has not been +% specified to \Lpack{latexrelease}. +%\begin{verbatim} +% \IncludeInRelease{2015/03/01}[2015/01/01]{\widget}{Widget Definition} +% \def\widget{even newer improved March version}% +% \EndIncludeInRelease +% +% \IncludeInRelease{2015/01/01}{\widget}{Widget Definition} +% \def\widget{new version}% +% \EndIncludeInRelease +% +% \IncludeInRelease{0000/00/00}{\widget}{Widget Definition} +% \def\widget{old version}% +% \EndIncludeInRelease +%\end{verbatim} +% +% Now, by default on a 2015/01/01 \LaTeX\ format, the first code block +% will compare the format date to the optional argument 2015/01/01 +% and so will execute the \emph{even newer improved} version. The +% remaining blocks using the |\widget| label argument will all then be +% skipped. +% +% If on the other hand the document requests an explicit release date +% using \Lpack{latexrelease} then this date will be used to decide what +% code block to include. +% +% \subsection{Using \cs{IncludeInRelease} in Packages} +% +% If |\IncludeInRelease| is used within a package then all such +% conditional code needs to be within such declarations, e.g., it is +% not possible in the above example to have the ``current'' definition +% of |\widget| somewhere in the main code and only the two older +% definitions inside |\IncludeInRelease| declarations. If you would do +% this then one of those |\IncludeInRelease| declarations would be +% included overwriting the even newer code in the main part of the +% package. As a result your package may get fragmented over time with +% various |\IncludeInRelease| declarations sprinkled throughout your +% code or you have to interrupt the reading flow by putting those +% declarations together but not necessarily in the place where they +% belong. +% +% To avoid this issue you can use the following coding +% strategy: place the current |\widget| definition in the main code +% where it correctly belongs. +% \begin{verbatim} +% ... +% \def\widget {even newer improved March version} +% \def\@widget{newly added helper command no defined in older releases} +% ... +%\end{verbatim} +% Then, near the end of your package place +% the following: +% \begin{verbatim} +% \IncludeInRelease{2015/03/01}[2015/01/01]{\widget}{Widget Definition} +% \EndIncludeInRelease +% +% \IncludeInRelease{2015/01/01}{\widget}{Widget Definition} +% \def\widget{new version}% +% \let\@widget\@undefined % this doesn't exist in earlier releases +% \EndIncludeInRelease +% +% \IncludeInRelease{0000/00/00}{\widget}{Widget Definition} +% \def\widget{old version}% +% \EndIncludeInRelease +%\end{verbatim} +% This way the empty code block hides the other |\IncludeInRelease| +% declarations unless there is an explicit request with a date +% 2015/01/01 or earlier. +% +% Now if you make a further change to |\widget| in the future you +% simply copy the current definition into the empty block and add a new +% empty declaration with todays date and the current format date. This +% way your main code stays readable and the old versions accumulate at +% the end of the package.\footnote{Of course there may be some cases +% in which the old code has to be in a specific place within the +% package as other code depends on it (e.g., if you +% \texttt{\string\let} something to it). In that case you have to +% place the code variations in the right place in your package rather +% than accumulating them at the very end.} +% +% The only other ``extra effort'' necessary when using this approach +% is that it may be advisable to undo new definitions in the code +% block for the previous release, e.g., in the above example we +% undefined |\@widget| as that isn't available in the 2015/01/01 +% release but was defined in the main code. If all your conditional +% code is within |\IncludeInRelease| declarations that wouldn't been +% necessary as the new code only gets defined if that release is +% chosen. +% +% \section{fixltx2e} +% +% As noted above, prior to the 2015 \LaTeX\ release updates to the +% \LaTeX\ kernel were not made in the format source files but were +% made available in the \Lpack{fixltx2e} package. That package is no +% longer needed but we generate a small package from this source +% that just makes a warning message but otherwise does nothing. +% +% +% +% +% +% \StopEventually{} +% +% \section{Implementation} +% +% We require at least a somewhat sane version of \LaTeXe{}. Earlier +% ones where really quite different from one another. +% \begin{macrocode} +%<*latexrelease> +\NeedsTeXFormat{LaTeX2e}[1996/06/01] +% \end{macrocode} +% +% \section{Setup} +% +% \begin{macro}{\IncludeInRelease} +% \begin{macro}{\EndIncludeInRelease} +% \begin{macrocode} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \changes{v1.0c}{2015/02/19}{Swap argument order} +% \begin{macrocode} +\DeclareOption*{% + \def\@IncludeInRelease#1[#2]{\@IncludeInRele@se{#1}}% + \let\requestedpatchdate\CurrentOption} +\DeclareOption{latest}{% + \let\requestedpatchdate\latexreleaseversion} +\DeclareOption{current}{% + \let\requestedpatchdate\fmtversion} +% \end{macrocode} +% +% \begin{macrocode} +\ExecuteOptions{current} +\ProcessOptions\relax +% \end{macrocode} +% +% Sanity check options, it allows some non-legal dates but always +% ensures |requestedLaTeXdate| gets set to a number. Generate an +% error if there are any non digit tokens remaining after removing the +% |//|. +% \begin{macrocode} +\def\reserved@a{% +\edef\requestedLaTeXdate{\the\count@}% +\reserved@b} +\def\reserved@b#1\\{% +\def\reserved@b{#1}% +\ifx\reserved@b\@empty\else +\PackageError{latexrelease}% + {Unexpected option \requestedpatchdate}% + {The option must be of the form yyyy/mm/dd}% +\fi} +\afterassignment\reserved@a +\count@\expandafter + \@parse@version\expandafter0\requestedpatchdate//00\@nil\\ +% \end{macrocode} +% +% less precautions needed for |\fmtversion| +% \begin{macrocode} +\edef\currentLaTeXdate{% + \expandafter\@parse@version\fmtversion//00\@nil} +% \end{macrocode} +% +% \begin{macrocode} +\ifnum\requestedLaTeXdate=\currentLaTeXdate +\PackageWarningNoLine{latexrelease}{% + Current format date selected, no patches applied.} +\expandafter\endinput +\fi +% \end{macrocode} +% +% A newer version of latexrelease should have been distributed with +% the later format. +% \begin{macrocode} +\ifnum\currentLaTeXdate + >\expandafter\@parse@version\latexreleaseversion//00\@nil +\PackageWarningNoLine{latexrelease}{% +The current package is for an older LaTeX format:\MessageBreak +LaTeX \fmtversion\space\MessageBreak +Obtain a newer version of this package!} +\expandafter\endinput +\fi +% \end{macrocode} +% can't patch into the future, could make this an error +% but it has some uses to control package updates +% so allow for now. +% \begin{macrocode} +\ifnum\requestedLaTeXdate + >\expandafter\@parse@version\latexreleaseversion//00\@nil +\PackageWarningNoLine{latexrelease}{% +The current package is for LaTeX \latexreleaseversion:\MessageBreak +It has no patches beyond that date\MessageBreak +There may be an updated version\MessageBreak +of this package available from CTAN} +\expandafter\endinput +\fi +% \end{macrocode} +% +% Update the format version to the requested date. +% \begin{macrocode} +\let\fmtversion\requestedpatchdate +\let\currentLaTeXdate\requestedLaTeXdate +% \end{macrocode} +% +% +% \section{Individual Changes} +% +% The code for each change will be inserted at this point, extracted +% from the kernel source files. +% +% \begin{macrocode} +%</latexrelease> +% \end{macrocode} +% +% \section{fixltx2e} +% +% Generate a stub \Lpack{fixltx2e} package: +% \begin{macrocode} +%<*fixltx2e> +\NeedsTeXFormat{LaTeX2e} +\PackageWarningNoLine{fixltx2e}{% +fixltx2e is not required with releases after 2015\MessageBreak +All fixes are now in the LaTeX kernel.\MessageBreak +See the latexrelease package for details} +%</fixltx2e> +% \end{macrocode} +% +% \Finale +% +\endinput |