%^^A* file information
% \iffalse
%
% alatex.dtx -- discussion and documentation of ALaTeX and its standard metaclass
%
% Copyright 1995 Matt Swift <
[email protected]>. All rights reserved.
%
% This file is part of the ALaTeX system.
% Please see the file 0areadme.txt for further information.
%
% All correspondence regarding ALaTeX should go to
% Matt Swift <
[email protected]>, not the LaTeX maintainers.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%
% \fi
%
%^^A* checks
%
%^^A NOTE: The character table, with two %'s, will get written to all files.
%% \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 \~}
%
% \CheckSum{287}
%
%^^A* abstract
% \begin{abstract}
% \ALaTeX{} is a document preparation system that provides the user with all
% the functionality of \LaTeX{} and a general, legal way to override standard
% \LaTeX{} behavior without altering source files. An important consequence is
% that \ALaTeX{} can interpret official \LaTeX{} markup in an abstract way.
%
% This discussion builds on the author's paper ``Modularity in \LaTeX''
% in the forthcoming TUGboat \textbf{16} (3).
% \end{abstract}
% \tableofcontents
% \clearpage
%
% \StopEventually{}
%
% \section{Introduction}
%
% The purpose of writing \ALaTeX{} was to facilitate typesetting official
% \LaTeX{} markup as \emph{abstract} markup, that is, markup that is not fixed
% to a ``standard'' appearance on a typeset page. Official \LaTeX{} markup has
% a standard appearance. Together with the broad portability of the \TeX{}
% program, this standard is a highly valuable feature of \LaTeX. In achieving
% this important goal, however, the \LaTeX{} developers compromised the
% valuable ability of \LaTeX{} to interpret markup abstractly. \ALaTeX{}
% attempts to provide users with the ability to process official \LaTeX{}
% markup with the power of full abstraction, without compromising their ability
% to process official \LaTeX{} markup in the standard way.
%
% You are not allowed to modify the distributed \LaTeX{} files without changing
% their names; yet filenames are how classes and packages are identified. In
% many cases it is desirable to produce \emph{different} \ext{dvi} files from
% the same source document. Suppose you make a small modification of the
% standard \class{article} class. To use it to process a source which calls
% for the \class{article} class, you must either break the law and call your
% derivative class \file{article.cls}, or modify the source to call for a
% different class. Both options are unacceptable, the first for obvious
% reasons, the second because a document class---and indeed all the markup in a
% source---ought to be abstractly descriptive without specifying the details of
% presentation. Font specifications are absurd in a document to be read aloud;
% volume specifications are absurd in a document to be printed; page
% specifications are absurd in a document to be viewed on a screen.
%
% Even were it agreed to privilege a single medium for presentation, sometimes
% the source simply cannot be modified, and making a copy would cause version
% control or storage difficulties, or itself be a violation of law.
%
% It is unnecessary to dwell on the necessary failure of any markup scheme to
% be suitably abstract for all interesting documents and presentation media.
% Fortunately, we are aiming to advance computer-aided typesetting, not the
% philosophy of essence and accident, syntax and semantics. What is true of
% \ALaTeX{} and not of \LaTeX{} is that all directives with a \emph{necessary}
% influence on typeset appearance appear outside the source document.
%
% It is very difficult to have a working \ALaTeX{} without also having a
% working \LaTeX. For this reason, \ALaTeX{} is unlikely to compromise the
% availability and ubiquity of systems that conveniently produce standard
% \LaTeX{} \ext{dvi} files from sources containing official \LaTeX{} markup.
% To help insure this harmlessness (and for lack of a reasonable alternative),
% \ALaTeX{} as distributed produces \ext{dvi} files identical to ones that
% \LaTeX{} produces from the same source. Differences are conceivable only in
% the perverse cases listed in Appendix \ref{perverse}.
%
% Abstracting those cases, therefore, a user must actively alter \LaTeX{} or
% \ALaTeX{} before she can produce a \ext{dvi} file that differs from the one
% standard \LaTeX{} produces from the same source file. \ALaTeX, however, is
% much easier to alter in useful ways than \LaTeX.
%
% \begin{em}
% When you compose a document, please preview it with (standard) \LaTeX.
% There is absolutely no reason at all to use \ALaTeX{} during document
% composition. Using \LaTeX{} will ensure that your document can be
% consistently compiled and viewed at every \LaTeX{} site in the world. Use
% \ALaTeX{} \emph{only} on existing sources when you can't or don't want to
% modify them, and yet want to present them in a nonstandard way.
% \end{em}
%
% \section{How \ALaTeX{} works}
%
% Most of the \ALaTeX{} distribution is designed to make a single small change
% to the \LaTeX{} kernel easy and legal to use. The change causes the
% |\documentclass| command to store its arguments in variables and load the
% file \file{metaclas.cfg} called the \term{metaclass} before continuing.
% That's it!
%
% The significance of this change is in the variety and scope of what can be
% accomplished by code in the metaclass. In the metaclass, the |@| character
% is a letter, as in normal class files.
%
% \DescribeMacro\mc@class@options
% \DescribeMacro\mc@class@name
% \DescribeMacro\mc@class@version
% When the metaclass is executed, the \ALaTeX{} kernel is loaded, and the
% source file has been processed from the beginning through the first
% |\documentclass| command and all its arguments. The arguments have been
% stored in macros as follows:
% \begin{description}
% \item[\bslash mc@class@options] holds the first optional argument to
% |\documentclass|.
% \item[\bslash mc@class@name] holds the mandatory argument to
% |\documentclass|.
% \item[\bslash mc@class@version] holds the second optional
% argument to |\documentclass|.
% \end{description}
%
% A metaclass can do anything at all with this information. The distributed
% metaclass below emulates \LaTeX's behavior. Code in comments below provides
% two convenient mechanisms to do something else, causing \ALaTeX's typeset
% documents to differ from \LaTeX's. \ALaTeX{} is as flexible as possible, and
% the number of other possibilities is countless.
%
% \DescribeMacro\alt@cls@extension
% \DescribeMacro\ds@foo
% The nonstandard mechanisms are as follows. Let \meta{class} be the class
% named by the |\documentclass| command, \meta{altX} be the value of
% |\alt@cls@extension| defined in the metaclass, and \meta{normX} be the value
% of |\@cls@extension| defined in the \ALaTeX{} (and \LaTeX) kernel.
% \begin{enumerate}
% \item When a file \file{\meta{class}.\meta{altX}} exists in the search path,
% it will be loaded instead of the usual \file{\meta{class}.\meta{normX}}.
% \item When a command |\ds@|\meta{class} is defined, it will be executed
% instead of loading \file{\meta{class}.\meta{normX}}.
% \end{enumerate}
%
% Notice that there is no reason to use \ALaTeX{} unless you create a
% nonstandard metaclass. The standard metaclass emulates standard \LaTeX{}
% because the user should have to take active steps to get nonstandard output.
% If you modify this file, please change the |\fileinfo| declaration near the
% end.
%
% \section{The game of the name}
%
% You may understand the \word{A} in \ALaTeX{} to stand for \word{alternate} or
% \word{abstract}, or to be the definite article, which emphasizes that fact
% that when you process with \ALaTeX{}, you are seeing just one of an infinite
% number of possibile presentations of your document's content.
%
% You may pronounce \ALaTeX{} however you like, of course.
%
% \section{A sampler of applications}
%
% \ALaTeX{} is a powerful tool, but newly born. Sophisticated applications
% have neither been conceived nor implemented. The author would appreciate
% hearing from you.
%
% \ALaTeX{} is potentially useful in situations where without \ALaTeX{} one
% would need to alter the source in a way that affects its presentation but not
% its content. For example, without \ALaTeX{} you must modify the source to
% change the paper size or font characteristics of the typeset document.
% \ALaTeX{} allows you to make this kind of change by altering the typesetting
% procedure instead of the source itself.
%
% You can use \ALaTeX{} to specify options to package and classes or even to
% load packages. You can invoke debugging or profiling code.
%
% Since the metaclass can control the style of a document, a system of files
% could be arranged in which there exist companion files for sources, which
% would function like style sheets. Common hierarchical path searching
% mechanisms would permit cascading styles with a flexible inheritance scheme
% at the levels of site, user, directory, and individual source.
%
% \section{The future}
%
% I envision removing most of the decisions embodied in the preamble and in
% package and class options from the source file to the invocation of the
% processing run. The decisions might be specified on the command line or in
% files separate from the source that are managed by a convenient interface.
% Is not an analogous development occurring as style sheets are brought to
% HTML?
%
% Since the choices a user would typically make via \ALaTeX{} are likely to be
% few and from among a small number of known alternatives, it is easy to
% imagine a convenient user interface for the common options. Such a front end
% written \TeX{} would have the advantage of being \%100 portable. A graphical
% interface could be integrated in an existing front end which manages a broad
% array of \TeX-related tasks.
%
% If metaclasses become tricky, a |\tracingmetaclasses| command might be
% warranted.
%
% \StopEventually{}
%
% \section{Version control}
%
% \begin{macro}{\fileinfo}
% \begin{macro}{\fileversion}
% \begin{macro}{\filedate}
% \begin{macro}{\docdate}
% \begin{macro}{\PPOptArg}
% First we take care of the business of keeping track of the version of this
% document.
% \begin{macrocode}
%<*metaclass>
\def\fileinfo{standard ALaTeX metaclass}
\def\fileversion{v1.0}
\def\filedate{1996/01/24}
\def\docdate{1996/01/24}
\edef\PPOptArg{\filedate\space \fileversion\space \fileinfo}
\ProvidesFile{metaclas.cfg}[\PPOptArg]
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \section{Emulate \LaTeX{} (the default)}
%
% \begin{macro}{\documentclass}
% \begin{macro}{\mc@load@class}
% The following |\documentclass| command behaves exactly like \LaTeX's. It
% looks a little different here because we've already read the three arguments.
% \begin{macrocode}
\def\documentclass{%
\let\documentclass\@twoclasseserror
\if@compatibility\else\let\usepackage\RequirePackage\fi
\mc@load@class}
\def\mc@load@class{%
\edef\reserved@a{%
\noexpand\@fileswithoptions
\noexpand\@clsextension
[\mc@class@options]{\mc@class@name}[\mc@class@version]}%
\reserved@a}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{Privelege alternate extensions}
%
% \begin{macro}{\alt@cls@extension}
% \begin{macro}{\documentclass}
% To enable divergences from standard \LaTeX{} of the first kind only,
% uncomment the following four definitions in this section and ensure that the
% definitions in following sections are commented out. Please also change the
% definition of |\fileinfo| above.
% \begin{macrocode}
% \def\alt@cls@extension{acl}
% \def\documentclass{%
% \let\documentclass\@twoclasseserror
% \if@compatibility\else\let\usepackage\RequirePackage\fi
% \IfFileExists{\mc@class@name.\alt@cls@extension}
% {\let\mc@extension\alt@cls@extension
% \mc@load@class
% \def\mc@extension{\@currext}}
% {\mc@load@class}}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\mc@extension}
% \begin{macro}{\@onefilewithoptions}
% A lot of code here for two tiny changes of |\@currext| to |\mc@extension|.
% The file with the alternate extension masquerades as one with the normal
% extension in every way except the actual filename.
% \begin{macrocode}
% \def\mc@extension{\@currext}
% \def\@onefilewithoptions#1[#2][#3]#4{%
% \@pushfilename
% \xdef\@currname{#1}%
% \global\let\@currext#4%
% \expandafter\let\csname\@currname.\@currext-h@@k\endcsname\@empty
% \let\CurrentOption\@empty
% \@reset@ptions
% \makeatletter
% \def\reserved@a{%
% \@ifl@aded\@currext{#1}%
% {\@if@ptions\@currext{#1}{#2}{}%
% {\@latex@error
% {Option clash for \@cls@pkg\space #1}%
% {The package #1 has already been loaded
% with options:\MessageBreak
% \space\space[\@ptionlist{#1.\@currext}]\MessageBreak
% There has now been an attempt to load it
% with options\MessageBreak
% \space\space[#2]\MessageBreak
% Adding the line:\MessageBreak
% \space\space\string\usepackage
% [\@ptionlist{#1.\@currext},#2]{#1}\MessageBreak
% to your document may fix this.\MessageBreak
% Try typing \space <return> \space to proceed.}}}%
% {\@pass@ptions\@currext{#2}{#1}%
% \global\expandafter
% \let\csname ver@\@currname.\@currext\endcsname\@empty
% \InputIfFileExists
% {\@currname.\mc@extension}%
% {}%
% {\@missingfileerror\@currname\mc@extension}%
% \let\@unprocessedoptions\@@unprocessedoptions
% \csname\@currname.\@currext-h@@k\endcsname
% \expandafter\let\csname\@currname.\@currext-h@@k\endcsname
% \@undefined
% \@unprocessedoptions}
% \@ifl@ter\@currext{#1}{#3}{}%
% {\@latex@warning@no@line
% {You have requested,\on@line,
% version\MessageBreak
% `#3' of \@cls@pkg\space #1,\MessageBreak
% but only version\MessageBreak
% `\csname ver@#1.\@currext\endcsname'\MessageBreak
% is available}}%
% \ifx\@currext\@clsextension\let\LoadClass\@twoloadclasserror\fi
% \@popfilename
% \@reset@ptions}%
% \reserved@a}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \section{Pass control to a macro}
%
% \begin{macro}{\documentclass}
% To enable divergences from standard \LaTeX{} of the second kind only,
% uncomment the following definition and ensure that all definitions in the
% next and previous sections are commented out. Please also change the
% definition of |\fileinfo| above. You must define |\dc@|\meta{class} in your
% \file{metaclass.cfg} or before the |\documentclass| command in your document,
% if you want to define it at all.
% \begin{macrocode}
% \def\documentclass{%
% \let\documentclass\@twoclasseserror
% \if@compatibility\else\let\usepackage\RequirePackage\fi
% \@ifundefined{dc@\mc@class@name}
% {\mc@load@class}
% {\@nameuse{dc@\mc@class@name}}}
% \end{macrocode}
% \end{macro}
%
% \section{First extension then macro}
%
% \begin{macro}{\documentclass}
% To enable divergences from standard \LaTeX{} of both the first and second
% kinds, uncomment the following definition as well as the definitions of
% |\alt@cls@extension|, |\mc@extension|, and |\@onefilewithoptions| above.
% Please also change the definition of |\fileinfo| above.
% \begin{macrocode}
% \def\documentclass{%
% \let\documentclass\@twoclasseserror
% \if@compatibility\else\let\usepackage\RequirePackage\fi
% \IfFileExists{\mc@class@name.\alt@cls@extension}
% {\let\mc@extension\alt@cls@extension
% \mc@load@class
% \def\mc@extension{\@currext}}
% {\@ifundefined{dc@\mc@class@name}
% {\mc@load@class}
% {\@nameuse{dc@\mc@class@name}}}}
% \end{macrocode}
% \end{macro}
%
% \section{Actually do something}
%
% So far we've just defined a command called |\documentclass|. It's time to
% use it. It's probably best if this remains at the end of the (extracted)
% file.
% \begin{macrocode}
\documentclass
% \end{macrocode}
%
% \begin{macrocode}
%</metaclass>
% \end{macrocode}
%
% \appendix
% \section{Perverse cases}
% \label{perverse}
%
% \ALaTeX{} as distributed produces \ext{dvi} files identical to ones that
% \LaTeX{} produces from the same source. Differences are conceivable
% only in the following perverse cases.
% \begin{enumerate}
% \item The document contains \TeX{} code that depends upon the exact
% definitions or undefined state of the macros
% \begin{quote}\raggedright
% |\ALaTeX|, |\documentclass|, |\mc@documentclass|,
% |\mc@@documentclass|, |\mc@class@options|, |\mc@class@name|,
% |\mc@class@version|, and |\mc@load@class|.
% \end{quote}
% \item Processing the document requires the (almost trivial) internal
% resources consumed by defining the above macros and loading the metaclass
% file.
% \item There is unfriendly code in the source before the |\documentclass|
% command. Normally only harmless comments and \env{filecontents}
% environments will precede the |\documentclass| command, but other code is
% possible, that would cause the \ALaTeX's output to differ from \LaTeX's.
% \item The arguments to |\documentclass| are very unusual, for example, they
% change catcodes or have complicated expansions. \ALaTeX{} scans the
% arguments to |\documentclass| slightly differently than \LaTeX{} does.
% \end{enumerate}
% No one should have to worry about these cases, and if they come up the
% problem should be obvious.
%
% \section{Kernel Patch}
%
% This is the code that patches the \LaTeX{} kernel.
%
% \begin{macrocode}
%<*alatex>
\def\fileinfo{ALaTeX patch to LaTeX kernel}
\def\fileversion{v1.0}
\def\filedate{1996/01/24}
\def\docdate{1996/01/24}
\edef\PPOptArg{\filedate\space \fileversion\space \fileinfo}
\ProvidesFile{metaclas.cfg}[\PPOptArg]
\makeatletter
% \end{macrocode}
%
% This is \ALaTeX, so make sure to announce it, and that it's nonstandard. We
% don't want to change the |\fmtversion|. We want \ALaTeX{} to masquerade as
% \LaTeX{} to the programs but not the users.
%
% This startup banner may be further modified by the code in |ltfinal.dtx| if a
% patch file is present.
% \begin{macrocode}
\everyjob{\typeout{ALaTeX\space<\fmtversion\space R1> (NOT STANDARD LATEX)}}
\immediate\write16{ALaTeX\space<\fmtversion\space R1> (NOT STANDARD LATEX)}
% \end{macrocode}
%
% \begin{macro}{\ALaTeX}
% Provide a logo.
% \begin{macrocode}
\DeclareRobustCommand{\ALaTeX}
{A\LaTeX}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\documentclass}
% \begin{macro}{\mc@documentclass}
% \begin{macro}{\mc@@documentclass}
% \begin{macro}{\mc@class@options}
% \begin{macro}{\mc@class@name}
% \begin{macro}{\mc@class@version}
% If the file |metaclas.cfg| exists in the search path, then the
% |\documentclass| command reads its three arguments (two are optional) into
% variables, and passes control to that file. If there is no such file, then
% we proceed just as in \LaTeX. Since |\documentstyle| loads some code then
% calls |\documentclass|, 2.09 documents also fall under the control of the
% metaclass mechanism.
% \begin{macrocode}
\def\documentclass{%
\IfFileExists{metaclas.cfg}
{\@ifnextchar[%]
{\mc@documentclass}
{\mc@documentclass[]}}
{\let\documentclass\@twoclasseserror
\if@compatibility\else\let\usepackage\RequirePackage\fi
\@fileswithoptions\@clsextension}}
\def\mc@documentclass[#1]#2{%
\@ifnextchar[%]
{\mc@@documentclass{#1}{#2}}
{\mc@@documentclass{#1}{#2}[]}}
\def\mc@@documentclass#1#2[#3]{%
\def\mc@class@options{#1}%
\def\mc@class@name{#2}%
\def\mc@class@version{#3}%
\makeatletter
\input{metaclas.cfg}%
\makeatother}
\@onlypreamble\documentclass
\@onlypreamble\mc@documentclass
\@onlypreamble\mc@@documentclass
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% Dump the format.
% \begin{macrocode}
\makeatother
\dump
% \end{macrocode}
%
% \begin{macrocode}
%</alatex>
% \end{macrocode}
%
% \Finale
