path: root/Master/texmf-dist/source/latex/prelim2e/prelim2e.dtx

% \iffalse meta-comment
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) Martin Schröder, 1994–2001
% 				Marei Peischl (peiTeX)  <marei@peitex.de>, 2020
%
% This work 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 work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is
%   Marei Peischl <marei@peitex.de>.
%
% This work consists of the files
% 	README.md
% 	prelim2e.dtx
% 	prelim2e.ins
% and the derived files
% 	prelim2e.sty
% 	prelim2e.pdf
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \fi
%     \changes{v1.01}{1995/05/02}{Date added to \cs{NeedsTeXFormat}}
%     \changes{v2.00}{2020/11/24}{Complete rework to use the kernel methods instead of everyshi}
% \iffalse
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesExplPackage{prelim2e}
%<package>         {2020/11/24}{2.0}{prelim2e Package}
%
%<*driver>
\ProvidesFile{prelim2e.drv}
      [2020/11/24 v2.0 Driver for prelim2e Package]
\documentclass{l3doc}
\usepackage{url}
\DeclareUrlCommand\CTANlink{\def\UrlLeft{CTAN:\space}\def\UrlRight{}\urlstyle{tt}}
\usepackage{geometry}
\usepackage[scrtime]{prelim2e}
\GetFileInfo{prelim2e.sty}
\EnableCrossrefs
\RecordChanges    % Gather update information
%%\DisableCrossrefs% Say \DisableCrossrefs if index is ready
\OnlyDescription  % comment out for implementation details
%%\OldMakeIndex    % use if your MakeIndex is pre-v2.9
\setcounter{IndexColumns}{2}
\oddsidemargin=2cm
\marginparwidth=2.5cm
% onecolumn glossary
\begin{document}
   \DocInput{prelim2e.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{104}
%
% \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         \~}
%
%
%
%  \renewcommand{\PrelimWords}{^^A
%     \package{prelim2e} package --
%     Version \fileversion --
%     Documentation \LaTeX{}ed^^A
%     }
%
%  \changes{v1.00}{1995/01/26}{New}
%  \changes{v1.21}{1998/08/09}{Documentation improved}
%  \changes{v1.22}{1999/06/08}{Moved to LPPL}
%  \changes{v1.3}{2009/05/29}{LPPL 1.3}
%
%  \newcommand*{\option}[1]{\textnormal{\sffamily#1}}
%  \newcommand*{\package}[1]{\textnormal{\sffamily#1}}
%  \newcommand*{\NEWfeature}[1]{%
%     \hskip 1sp \marginpar{\small\sffamily\raggedright
%     New feature\\#1}}
%  \newcommand*{\NEWdescription}[1]{%
%     \hskip 1sp \marginpar{\small\sffamily\raggedright
%     New description\\#1}}
%
%  \pagestyle{headings}
%
%
% ^^A -----------------------------
%
%  \title{\unskip
%   The \package{prelim2e} package^^A
%        }
%  \author{Martin Schröder\thanks{maintained by Marei Peischl <marei@peitex.de>}}
%  \maketitle
%
% ^^A -----------------------------
%
%
%  \begin{abstract}
%     This package allows the marking of (preliminary) versions of a
%     document on the output.
%  \end{abstract}
%
% ^^A -----------------------------
%
%  \tableofcontents
%
% ^^A -----------------------------
%
%  \section{Introduction}
%  ^^A
%  This package allows the marking of (preliminary) versions of a
%  document.
%  This is done using the command \cs{PrelimText}, whose expansion
%  is added \emph{below the footer} of every page of a document (look
%  at the bottom of this page for an example).
%
% ^^A -----------------------------
%
%  \section{Requirements}
%  Version 2.00 requires the kernel hook management and is no longer
%  useable with LaTeX versions older than 2020/10/01. In case you have
%  any understandable  reason, which requires the old implementation,
%  feel free to contact the maintainer.
%
% ^^A -----------------------------
%
%  \section{Usage}
%  ^^A
%  Simply using this package via 
%  \mbox{\cs{usepackage}\texttt{\{}\package{prelim2e}\texttt{\}}} produces a
%  text in the form of ``Preliminary version -- \today''.
%
% \begin{function}{\PrelimText,\PrelimWords}
%  The text is produced by the commands \cs{PrelimText} and 
%  \cs{PrelimWords}, which can be changed via \cs{renewcommand} or by 
%  using options at the \cs{usepackage} command (see 
%  section~\ref{sec:options}).
%
%  The footer for this documentation was produced by changing 
%  \cs{PrelimWords} to
%\begin{verbatim}
%  \renewcommand*{\PrelimWords}{%
%    \textsf{prelim2e} package --
%    Version \fileversion --
%    Documentation \LaTeX{}ed%
% }
%\end{verbatim}
% \end{function}
%
%  \begin{function}{\PrelimTextStyle}
%  The style of the Text can be controlled by \cs{PrelimTextStyle}. This can also be adjusted using \cs{renewcommand*}. The default is set empty, but will use the default font in footnotesie.
%  \end{function}
%
% ^^A -----------------------------
%
%  \section{Options}
%  \label{sec:options}
%  ^^A
%  The package has the following options:
%  \nopagebreak
%  \begin{description}
%     \item[\normalfont\option{danish}]
%           \changes{v1.23}{2001/02/17}{\option{danish} option added}
%           \NEWfeature{2001/02/17}
%        This sets the text to ``Forel\o{}big version''.
%        It does not use the \package{babel} package.
%     \item[\normalfont\option{draft}]
%        If this option is used a text appears below the normal 
%        pagebody.
%        It is the default.
%     \item[\normalfont\option{final}]
%        If this option is used \package{prelim2e} produces no text.
%     \item[\normalfont\option{english}]
%        This sets the text to ``Preliminary version''.
%        It is the default.
%     \item[\normalfont\option{french}]
%           \changes{v1.20}{1997/05/12}{\option{french} option added}
%           \NEWfeature{1997/05/12}
%        This sets the text to ``Version pr\'eliminaire''.
%        It does not use the \package{french} or \package{babel} package.
%     \item[\normalfont\option{german}]
%        This sets the text to ``Vorl\"aufige Version''.
%        It does not use the \package{german} or \package{babel} package.
%     \item[\normalfont\option{italian}]
%           \changes{v1.23}{2001/02/17}{\option{italian} option added}
%           \NEWfeature{2001/02/17}
%        This sets the text to ``Versione preliminare''.
%        It does not use the \package{babel} package.
%     \item[\normalfont\option{norsk}]
%           \changes{v1.3}{2009/05/29}{\option{norsk} option added}
%           \NEWfeature{2009/05/29}
%        This sets the text to ``Forel\o{}pig versjon''.
%        It does not use the \package{babel} package.
%     \item[\normalfont\option{time}]
%           \changes{v1.10}{1996/01/01}{\option{time} option added}
%           \NEWdescription{1997/05/12}
%        This adds the time at the beginning of the current \LaTeX{}
%        to the text.
%        The time is produced using the \cs{thistime} command, which may
%        be provided by the \package{scrtime} package\cite{package:scrtime}.
%        If you don't use the \package{scrtime} package (e.\,g. by 
%        specifying the \option{scrtime} option), you must
%        provide it yourself or by some other package.
%     \item[\normalfont\option{scrtime}]
%           \changes{v1.20}{1997/05/12}{\option{scrtime} option added}
%           \NEWfeature{1997/05/12}
%        This loads the \package{scrtime} package\cite{package:scrtime} 
%        (part of the KOMA-Script bundle), which provides the 
%        \cs{thistime} command used by the \option{time} option.
%        The \option{scrtime} option implies the \option{time} option.
%  \end{description}
%  All other options are passed to the \package{scrtime} package if the
%  \option{scrtime} option is selected.
%
%
% ^^A -----------------------------
%
%  \section{Required packages}
%  ^^A
%  The package requires the following packages:
%  \begin{description}
%     \item[\normalfont\package{scrtime}\cite{package:scrtime}]
%           \changes{v1.10}{1996/01/01}{\package{scrtime} instead of 
%              \package{printtim}}
%           \NEWdescription{1997/05/12}
%        It is used to typeset the current time and is needed if the 
%        \option{scrtime} option is selected.
%  \end{description}
%
%
% ^^A -----------------------------
%
%  \section{Putting more things at the bottom}
%  ^^A
%  Another package you might like to use with \package{prelim2e} is 
%  \package{vrsion}\cite{package:vrsion}.
%  This allows the definition and maintenance of a version number like
%  3.14159 \emph{within \LaTeX}, which can be put at the bottom of every
%  page using \package{prelime2e}.
%
%
% ^^A -----------------------------
%
% ^^A -----------------------------
%
%  \section{Acknowledgements}
%  ^^A
%  The idea of this package is based on 
%  \texttt{prelim.sty}\cite{package:prelim} for \LaTeX2.09 by Robert 
%  Tolksdorf (\texttt{tolk@cs.tu-berlin.de}).
%  It provides nearly the same functionality as \package{prelim2e}, but
%  in a very dirty way: it uses a modified output routine and does not 
%  work with \LaTeXe.
%
%  The time functionality now uses the \package{scrtime} package by
%  Markus Kohm (\texttt{markus.kohm@gmx.de}).
%
%  Rowland Bartlett (\texttt{R.BARTLETT@liverpool-john-moores.ac.uk})
%  brought forth the idea of separating the \option{time} option and the
%  \package{scrtime} package; 
%  Daniel Courjon (\texttt{dcourjon@utinam.univ-fcomte.fr}) provided
%  the text for the \option{french} option,
%  Arne J\o{}rgensen (\texttt{arne.jorgensen@tug.dk}) 
%  provided the text for the \option{danish} option,
%  Davide Giovanni Maria Salvetti (\texttt{salve@debian.org}) 
%  and Riccardo Murri (\texttt{murri@phc.unipi.it}) 
%  both provided the text for the \option{italian} option,
% and Sveinung Heggen (\texttt{sveinung.heggen@orkla.no}) provided the
% text for the \option{norsk} option.
%
%  As usual Rebecca Stiels improved the quality of this documentation.
%
%
% ^^A -----------------------------
%
%  \begin{thebibliography}{1}
%     \raggedright
%     \bibitem{package:prelim}
%        Mats Dahlgren.
%        \newblock \package{vrsion} -- a \LaTeX{} Macro for version 
%           Numbering of Files.
%        \newblock \CTANlink{tex-archive/macros/latex/contrib/supported/vrsion/vrsion.dtx}.
%        \newblock \LaTeXe{} package.
%     \bibitem{package:scrtime}
%        Markus Kohm.
%        \newblock The \package{KOMA}-timedate-bundle.
%        \newblock \CTANlink{tex-archive/macros/latex/contrib/supported/koma-script/scrtime.dtx}.
%        \newblock \LaTeXe{} package.
%     \bibitem{package:vrsion}
%        Robert Tolksdorf.
%        \newblock Kennzeichnung von Vorversionen eines Dokuments.
%        \newblock \CTANlink{tex-archive/macros/latex209/contrib/prelim/}.
%        \newblock \LaTeX2.09 package.
%  \end{thebibliography}
%
% \StopEventually{\PrintChanges}
%
% ^^A -----------------------------
%
%  \section{The implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    \begin{macrocode}
%<@@=prelim>
%    \end{macrocode}

%
% ^^A -----------------------------
%
%  \subsection{Initial Code}
%  The implementation of version 2.00 requires a the kernel's hook management.
%  Therefore we test if it's available and throw an error message if not. 
%
%    \begin{macrocode}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
\IfFormatAtLeastTF{2020/10/01}{}{%
  \PackageError{prelim2e}{
    Format file is too old. Please update your LaTeX distribution.
  }{
    prelim2e of version 2.0 requires a format version of at least 2020/10/01
  }%
}
%    \end{macrocode}

%  ^^A
%  \begin{variable}{\g_prelim_draft_bool}
%  \cs{g_prelim_draft_bool} is used to flag the use of the \option{draft}
%  or \option{final} option.
%    \begin{macrocode}
\bool_new:N \g_prelim_draft_bool
%    \end{macrocode}
%  \end{variable}
%
%  \begin{variable}{\g_prelim_time_bool}
%     \changes{v1.10}{1996/01/01}{new}
%  \cs{g_prelim_time_bool} is used to flag the use of the \option{time}
%  option.
%    \begin{macrocode}
\bool_new:N \g_prelim_time_bool
%    \end{macrocode}
%  \end{variable}
%
%  \begin{variable}{\g_prelim_scrtime_bool}
%     \changes{v1.20}{1997/05/12}{new}
%  \cs{g_prelim_scrtime_bool} is used to flag the use of the \option{scrtime}
%  option.
%    \begin{macrocode}
\bool_new:N \g_prelim_scrtime_bool
%    \end{macrocode}
%  \end{variable}
%
%
%  \begin{macro}{\PrelimWords}
%  \cs{PrelimWords} holds the language-dependend text used in 
%  \cs{PrelimText}
%    \begin{macrocode}
\newcommand*{\PrelimWords}{}
%    \end{macrocode}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{Declaration of options}
%
% ^^A -----------------------------
%
%
%  \subsubsection{\option{draft} option}
%  ^^A
%  The \option{draft} and \option{final} option control the behavior
%  of \package{prelim2e}: Only if \option{final} is used in 
%  \cs{documentclass} or 
%  \mbox{\cs{usepackage}\texttt{\{}\package{prelim2e}\texttt{\}}} text is
%  produced.
%    \begin{macrocode}
\DeclareOption{draft}{\bool_gset_true:N \g_prelim_draft_bool}
\DeclareOption{final}{\bool_gset_false:N \g_prelim_draft_bool}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsubsection{Language options}
%  ^^A
%  \option{danish}, \option{english}, \option{french}, \option{german},
%  \option{italian} and \option{norsk} control the content of \cs{PrelimWords}.
%     \changes{v1.20}{1997/05/12}{\option{french} option added}
%     \changes{v1.23}{2001/02/17}{\option{danish} option added}
%     \changes{v1.23}{2001/02/17}{\option{italian} option added}
%     \changes{v1.3}{2009/05/29}{\option{norsk} option added}
%    \begin{macrocode}
\DeclareOption{danish}{%
   \renewcommand{\PrelimWords}{Forel\o{}big~version}}
\DeclareOption{english}{%
   \renewcommand{\PrelimWords}{Preliminary~version}}
\DeclareOption{french}{%
   \renewcommand{\PrelimWords}{Version~pr\'eliminaire}}
\DeclareOption{german}{%
   \renewcommand{\PrelimWords}{Vorl\"aufige~Version}}
\DeclareOption{italian}{%
   \renewcommand{\PrelimWords}{Versione~preliminare}}
\DeclareOption{norsk}{%
  \renewcommand{\PrelimWords}{Forel\o{}pig~versjon}}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsubsection{Time options}
%  ^^A
%     \changes{v1.10}{1996/01/01}{\option{time} option added}
%  \option{time} controls the output of the current time at
%  \cs{PrelimWords}.
%    \begin{macrocode}
\DeclareOption{time}{\@prelim@timetrue}
%    \end{macrocode}
%
%     \changes{v1.20}{1997/05/12}{\option{scrtime} option added}
%  \option{scrtime} controls the loading of the \package{scrtime} 
%  package.
%  It implies \option{time}.
%    \begin{macrocode}
\DeclareOption{scrtime}{
	\bool_gset_true:N \g_prelim_scrtime_bool
	\bool_gset_true:N \g_prelim_time_bool
}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsubsection{Other options}
%  ^^A
%     \changes{v1.20}{1997/05/12}{check \cs{if@prelim@scrtime}}
%     \changes{v1.10}{1996/01/01}{\cs{DeclareOption*} added}
%  All unused options are passed to the \package{scrtime} package if 
%  the \option{scrtime} option is selected.
%    \begin{macrocode}
\DeclareOption*{%
   \bool_if:NT \g_prelim_scrtime_bool {
      \PassOptionsToPackage{\CurrentOption}{scrtime}%
	}
}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{Executing options}
%  ^^A
%  The default options are \option{draft} and \option{english}.
%    \begin{macrocode}
\ExecuteOptions{draft,english}
\ProcessOptions\relax
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{Loading packages}
%  ^^A
%     \changes{v1.20}{1997/05/12}{check \cs{if@prelim@scrtime}}
% 	  \changes{v2.00}{2020/11/24}{remove \package{everyshi}}
%  We need the \package{scrtime} package if the \option{scrtime} option is specified.
%    \begin{macrocode}
\bool_if:NT \g_prelim_scrtime_bool {
   \RequirePackage{scrtime}
}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{Producing the text}
%  ^^A
%  \begin{macro}{\PrelimText}
%     \changes{v1.10}{1996/01/01}{\cs{thistime} instead of \cs{PrintTime}}
%  \cs{PrelimText} produces the text which is put below the page.
%  It can be changed via \cs{renewcommand}.
%  The style of the text is controlled by \cs{PrelimTextStyle}.
%  We first have to reset the style and size, otherwise the settings in
%  effect at the point of text where \cs{ouput} is called would be used.
%    \begin{macrocode}
\newcommand{\PrelimText}{
  \textnormal{
    \footnotesize
    \PrelimTextStyle
    \PrelimWords{}~--~\today~
    \bool_if:NT \g_prelim_time_bool {
      \ --~
      \thistime~
   }
  }
}
%    \end{macrocode}
%  \end{macro}
%  \begin{macro}{\PrelimTextStyle}
%  \cs{PrelimTextStyle} controls the style of the text produced by
%  \cs{PrelimText}.
%  It's default is empty.
%    \begin{macrocode}
\newcommand{\PrelimTextStyle}{}
%    \end{macrocode}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{Putting the text below the page}
%  ^^A
% \changes{v2.00}{2020/11/24}{Use \LaTeX{} kernel method instead of everyshi}
%  We put the text below the page via \cs{AddtoHook{shipout/foreground}}.
%  This is done by \cs{\__prelim_every_shipout:}.
%
% Save the shipout origins to macros to adjust the position of the the
% PrelimText similar to the older versions of prelim2e.
%    \begin{macrocode}
\tl_const:Nx \c__prelim_horigin_tl {
  \tl_if_exist:NTF \c__shipout_horigin_tl {
    \c__shipout_horigin_tl
  } {
    1in
  }
}

\tl_const:Nx \c__prelim_vorigin_tl {
  \tl_if_exist:NTF \c__shipout_vorigin_tl {
    \c__shipout_vorigin_tl
  } {
    1in
  }
}

%    \end{macrocode}
%  \begin{function}{\__prelim_every_shipout:}
%  \changes{v1.10}{1996/01/01}{\cs{hbox to}$\rightarrow$\cs{hb@xt@}}
%  \changes{v1.24}{2004/03/28}{Bugfix: Add missing \%.
%                              Bug reported by Carsten Heinz (\texttt{cheinz@gmx.de}).}
%  \cs{@Prelim@EveryShipout} puts the text produced by \cs{PrelimText}
%  below the page. We do this using expl3-Syntax to directly access the measures of
%  the shipout box.
%    \begin{macrocode}
\cs_new:Nn \__prelim_every_shipout: {
%    \end{macrocode}
%  We calculate the text position to match the implementation for versions before 2.0.
%    \begin{macrocode}
\put(\c__shipout_horigin_tl,\dim_eval:n {
    -\c__shipout_vorigin_tl-\l_shipout_box_ht_plus_dp_dim-\topskip
  })
  {
    \vbox_to_ht:nn {0pt} {
      \hbox_to_wd:nn {\l_shipout_box_wd_dim} {
        \let\protect\relax
        \hfill\PrelimText\hfill
      }
    }
  }
}
%    \end{macrocode}
%  \end{function}
%
%
% ^^A -----------------------------
%
%  \subsection{Tieing \package{prelim2e} into the system}
%  ^^A
%  \cs{@Prelim@EveryShipout} is tied into the system using the
%  kernel's hook management.
%  But only if the \option{draft} option is used.
%    \begin{macrocode}
\bool_if:NT \g_prelim_draft_bool {
  \AddToHook{shipout/foreground}{\__prelim_every_shipout:}
}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \Finale
% ^^A