path: root/macros/alatex/alatex-1.0/alatex.dtx

%^^A* file information
% \iffalse
%
% alatex.dtx -- discussion and documentation of ALaTeX and its standard metaclass
%
%   Copyright 1995 Matt Swift <swift@bu.edu>.  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 <swift@bu.edu>, 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