summaryrefslogtreecommitdiff
path: root/macros/alatex/alatex-1.0/alatex.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/alatex/alatex-1.0/alatex.dtx
Initial commit
Diffstat (limited to 'macros/alatex/alatex-1.0/alatex.dtx')
-rw-r--r--macros/alatex/alatex-1.0/alatex.dtx531
1 files changed, 531 insertions, 0 deletions
diff --git a/macros/alatex/alatex-1.0/alatex.dtx b/macros/alatex/alatex-1.0/alatex.dtx
new file mode 100644
index 0000000000..0f7539b569
--- /dev/null
+++ b/macros/alatex/alatex-1.0/alatex.dtx
@@ -0,0 +1,531 @@
+%^^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