README: -*-text-*- describing the XPPT beta-test document style.

XPPT is a document style for AMS-TeX that extend the standard AMSPPT
`preprint' and compatible styles.  Highlights include

* cross-references,
* automatic numbering of headings, captions, and theorems,
* table of contents generation,
* Bib-TeX bibliography interface,
* inclusion of `verbatim' program text, and
* options for 8-bit characters, RCS interface, and much more.

The only manual currently available is the text below that summarises
the features; further details can be found in the technical
documentation in the individual *.doc files.  There will be no proper
manual until there is a proper release!

DISCLAIMER: The XPPT document style 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.

In fact, since this is a test release, I encourage you to write your
opinions and wishes to the author at the email address below!

This file last updated on $Date: 1992/01/28 06:58:52 $
---------------------------------------------------------------------------
CONTENTS:

	-1- Notes & acknowledgements
	-2- XPPT document style extensions
	-3- XPPT option summary
	-4- Fixes for the AMSPPT document style version 2.1
	-5- Log

===========================================================================
	-1- NOTES & ACKNOWLEDGEMENTS
===========================================================================

INSTALLATION: Edit the provided Makefile and run make install or do
the following: 

	copy	xppt.doc	to	TEXINPUTS/xppt.tex
		pptfixes.doc		TEXINPUTS/pptfixes.tex
		xfixed.doc		TEXINPUTS/xfixed.tex
		xlatin1.doc		TEXINPUTS/xlatin1.tex
		xrcs.doc		TEXINPUTS/xrcs.tex


	copy	xppt.bst	to	TEXINPUTS/xppt.bst

------------------------------------------------------------------------
AUTHOR: XPPT has been written by me,

	Kristoffer H{\o}gsbro ROSE                      <kris@diku.dk>
	DIKU (TOPPS group), University of Copenhagen
	Universitetsparken 1, DK-2100 Copenhagen {\O}   (+45) 31396466

in 1991 and 1992. A prototype version is distributed with the XY-pic
diagram typesetting macros where they are used to format the manual,
however, the prototype actually modifies AMSPPT and thus is not really
a set of extensions.

However, XPPT would not have existed if it had not been for the very
nice and typographically well-designed format that it extends: it is
based on the conventions in version 2.1 of the AMSPPT document style,
and requires AMS-TeX version 2.1.  AMS-TeX is the TeX typesetting
system of the American Mathematical Society; for further information
you should contact the AMS:

	American Mathematical Society
	Technical Support Group
	P. O. Box 6248; Providence, RI 02940; USA
	401-455-4080 or (in the USA) 800-321-4AMS
	Internet: Tech-Support@Math.AMS.com.

If you use LaTeX with a lot of mathematics, and you are tired of
strange spacing around displays and an infinite number of `Overfull
hbox...' messages then I recommend AMS-TeX!  It even has a very
well-written and useful manual...

I would like to thank Walter Neumann, Oren Patashnik, and Walter F.
Tichy, for the code that they have made available to the world without
which XPPT would not be much fun; Michael D. Spivak and others at
the American Mathematical Society for AMS-TeX; and finally to Donald
E. Knuth for designing TeX in the first place!


======================================================================
  	-2- XPPT DOCUMENT STYLE EXTENSIONS
======================================================================

  	XPPT extends the capabilities for handling visual structure that are
  	present in the AMSPPT document style by adding commands for boring
  	tasks like generating the table of contents and keeping track of
  	cross references.

  	-2.1- Introduction
  	-2.2- The AUX-file
  	-2.3- Cross-references
  	-2.4- Automatic numbering
  	-2.5- Automatic table of contents
  	-2.6- Bib-TeX bibliographies
  	-2.7- Miscellaneous
  	-2.8- Missing features

----------------------------------------------------------------------
  	-2.1- INTRODUCTION
----------------------------------------------------------------------

  	The XPPT document style does not redefine anything that is defined in
  	AMSPPT.STY, and should thus work with any document style that follows
  	the same conventions as AMSPPT.STY does, and documents written for
  	such styles should not be affected by the extensions.  Once you use
  	the extensions, however, there are certain restrictions on some of
  	the commands; they are listed where relevant.

  	The commands listed below are classified into groups according to
  	where they should appear:

  	  <PREAMBLE>	between \documentstyle and \topmatter
  	  <TOPMATTER>	between \topmatter and \endtopmatter
  	  <TOC>		between \toc and \endtoc
  	  <PARAGRAPH>	between paragraphs (`vertical' mode)
  	  <TEXT>	in headings and paragraphs (`horizontal' mode)
  	  <OUTER TEXT>	only in paragraphs in the document body
  	  <MATH>	between $ and $ or $$ and $$ (`math mode')
  	  <REFS>	between \Refs and \endRefs

  	There are a few features that, when used, require extra actions to be
  	taken by the user.  Such extra actions are described by a paragraph
  	headed by "WARNING: ".

  	You can check whether XPPT is loaded:

  \ifx\xpptloaded\undefined (1) \else (2) \fi
  	Do (1) if XPPT is not loaded, otherwise perform (2).  (1) and (2)
  	should only contain \define... commands.

----------------------------------------------------------------------
  	-2.2- THE AUX-FILE
----------------------------------------------------------------------

  	Most of the features discussed below are handled by storing
  	definitions during each run in a file such that they are available at
  	the beginning of the next run.  This file is called the AUX-file
  	because one of the supported features requires it: Bib-TeX expects to
  	find special commands in a file called something with .AUX at the
  	end.

  	The AUX-file will be read and recreated by \topmatter, but the
  	recreation can be prevented:

  \InhibitUpdate						<PREAMBLE>
  	Inhibit updating of cross references, the table of contents, etc..
----------------------------------------------------------------------
  	-2.3- CROSS-REFERENCES
----------------------------------------------------------------------

  	Cross-references share the AUX-file the bibliographic references:
  	each \xlabel reference leaves a cookie there that will be available
  	using \xref after the AUX-file has been read.  There is no special
  	provision for page numbers in cross references since then it might be
  	necessary to run TeX many times on the same file to get them right.
  	Also this means that journals will have to run TeX more than once
  	using their style and this is not the intention (see the discussion
  	in the section on the AUX-file).

  \xlabel {KEY} {TEXT} 						<TEXT>
  	Defines KEY as a cross-reference label that will appear as TEXT at
  	references.

  \xref "DEFAULT" {KEY}						<TEXT>
  	Expands to the TEXT of the cross-reference with label KEY; if there
  	is no such reference then expand to DEFAULT (if omitted then assume
  	it was given as "\fiverm KEY\W@{! Undefined reference: KEY.}").

----------------------------------------------------------------------
  	-2.4- AUTOMATIC NUMBERING
----------------------------------------------------------------------
  	XPPT supports automatic numbering in the style of \item of AMSPPT's
  	\roster...\endroster for the following classes of
  	structures from AMSPPT: SECTION HEADINGS, THEOREMS, ROSTERS, and
  	CAPTIONS.  This is done by assigning a LEVEL and a FORM to each
  	actual command of each class that should be automatically numbered:
  	then the command will automatically generate a number depending on
  	the NUMBER REF arguments that immediately follow it.

  WARNING: Currently this does not mix with \nofrills.  The author is unsure
  of how the semantics of this should be.  Any suggestions?

  	A LEVEL is a single digit and the FORM is any text.  LEVEL 0 is a
  	dummy level that has no effect; LEVEL 1 through 9 represent
  	independent counters where it is possible to insert the current
  	value using #LEVEL, i.e., a # followed by a single digit.

  \level LEVEL {PUNCT}						<PREAMBLE>
  	Insert the value of the current LEVEL counter followed by punctuation
  	PUNCT unless the level is void.

  	The NUMBER and REF optional arguments should have this form:

  	1) NUMBER determines how the LEVEL counter should be set before being
  	output using the FORM:
  	   * Omitted  : incremented and formatted using FORM,
  	   * [NUMBER] : set to NUMBER and formatted using FORM, or
  	   * "TEXT"   : not touched: use TEXT for LEVEL and ignore FORM.

  	2) REF makes it possible to generate a cross reference:
  	   * Omitted  : no cross reference, or
  	   * ={KEY}   : equivalent to \xlabel{KEY}{STUFF} where STUFF is the
  			formatted number.

  	Furthermore, all entities that have been declared in this way will
  	automatically generate a table of contents cookie in the AUX-file
  	(see below how to make use of these to generate a ToC automatically).

  	This is all implemented by three commands that are used for the three
  	kinds of syntax used by AMSPPT for this kind of thing:

  \NumberHead {COMMAND} LEVEL {SUBLEVELS} {FORM}
  \NumberFirst {COMMAND} LEVEL {SUBLEVELS} {FORM}
  \NumberLast {COMMAND} LEVEL {SUBLEVELS} {FORM}
  	Initiate automatic numbering of COMMAND using the LEVEL counter
  	(should be specified without the leading \, i.e., {head}).  The first
  	form should be used for commands that are on the form \COMMAND ...
  	\endCOMMAND (like \head), and the next two forms should be used for
  	commands on the form \COMMAND{...} where the number should come
  	first/last (e.g., these are appropriate for \proclaim).

  	The following COMMANDs are allowed with AMSPPT in each case:

  	For \NumberHead: head, subhead, subsubhead, and specialhead.
  	For \NumberFirst and \NumberLast: proclaim, demo, definition,
  		example, remark, topcaption, and botcaption.

----------------------------------------------------------------------
  	-2.5- AUTOMATIC TABLE OF CONTENTS
----------------------------------------------------------------------

  	An automatic table of contents can be constructed from the cookies
  	left by heading commands declared with \NumberHead... above.  Since
  	the table of contents can appear anywhere we collect it in a token
  	list while reading the AUX-file.

  	The user uses the following command to insert the entire generated
  	table of contents within an ordinary \toc...\endtoc:

  \autotoc							<TOC>
  	Inserts the entire contents of the token list.  Must appear after
  	\topmatter and within \toc...\endtoc.


  	However, even though the actual table of contents is generated
  	automatically, XPPT does not insert \widestnumber and spacing entries
  	in the \autotoc.  You must do this with the following commands at the
  	points in the document corresponding to the point in the table of
  	contents where these commands should appear:

  \tocwidestnumber {COMMAND} {NUMBER}
  	Generate a cookie that inserts a \widestnumber\COMMAND{NUMBER} at the
  	corresponding point in the table of contents.

  \tocvspace {DIMENSION}
  	Generate a cookie that inserts a vertical space of DIMENSION at the
  	corresponding point in the table of contents.

----------------------------------------------------------------------
  	-2.6- BIB-TeX BIBLIOGRAPHIES
----------------------------------------------------------------------

  	These commands allow you to use Bib-TeX bibliography databases and
  	yet generate bibliographies in the AMSPPT format.  These commands
  	work in the delayed fashion of Bib-TeX: \bibrefs will only include
  	all references that the last run of the bibtex(1) command generated
  	from the AUX-file; at the same time \UseBibRefs defines those
  	BIB-files that will be used by the next run of bibtex.  \cite will
  	issue a warning message if a KEY is not known. This facility is
  	triggered by the \UseBibRefs command, in particular \cite will be the
  	`old' one until then.

  \refstyle {STYLE}						<PREAMBLE>
  	Like AMSPPT \refstyle...but also sets up BibTeX interface parameters.
  	The default is \refstyle{A}.

  WARNING: There is no way for XPPT to figure out what \refstyle the document
  style has chosen so we just assumes that it was \refstyle{A} (as it is the
  case for AMSPPT).  This is very stupid; it means that the user must repeat
  the \refstyle definition of the document style if it was \refstyle{B} or
  \refstyle{C} to get the same behaviour from the BibTeX references.  Sorry.
  This is particularly stupid since users might want to make macros
  conditional on the \refstyle in use to be able to write references that
  appear either as "Rose [Ros92]", "(Rose 1992)", or "Rose [1]".  A portable
  way of changing it is to place the \refstyle in \topmatter; this also
  effectively prevents the user from changing it!

  \UseBibRefs{FILES}						<PREAMBLE>
  	Preamble command that declares this run to use Bib-TeX bibliographic
  	references from the BIB-files FILES (should be a comma-separated list
  	of BIB-file names without the .bib extension).

  \cite "PRETEXT" [COMMENT2] {KEYS,_COMMENT1}			<TEXT>
  \incite "PRETEXT" [COMMENT2] {KEYS,_COMMENT1}			<TEXT>
  	Cite the Bib-TeX reference(s) specified by KEYS and augmented by the
  	optional PRETEXT, COMMENT1, and COMMENT2 arguments as follows:

  	1) If the citation does not includes the full name of the author and
  	a "PRETEXT" argument is present then typeset PRETEXT .

  	2) Interpret the KEYS and typeset the associated identifications
  	according to the chosen \refstyle.  KEYS should be a comma-separated
  	list of single KEYs without spaces.

  	3) If COMMENT1 is present, i.e., KEYS are followed by ,_ (comma
  	space), then typeset it.  If COMMENT2 is present then typeset it.

  	You should normally use \cite; \incite is for references that appear
  	within parenthesis (some formats use a different style for those).

  \nocite {KEYS}						<TEXT>
  	Like \cite, but the Bib-TeX references will not be inserted in the
  	text, just in the bibliography.  \nocite{*} will include all
  	references of the  in the 

  \bibrefs							<REFS>
  	Inserts the entire list of Bib-TeX bibliographic references in a
  	format acceptable within \Refs...\endRefs.

  	XPPT interfaces to Bib-TeX by defining a lot of control sequences
  	that are then used by the special Bib-TeX style XPPT.BST.  You may
  	consult XPPT.BST for a list of what should be defined.

----------------------------------------------------------------------
  	-2.7- MISCELLANEOUS
----------------------------------------------------------------------

  \today							<TEXT>
  	Contains the TeX start date on the form MONTH DAY, YEAR.

  \now								<TEXT>
  	Contains the TeX start time on the form HOUR:MINUTES.

  \commentcharacter						<TEXT>
  \escapecharacter						<TEXT>
  \bgroupcharacter						<TEXT>
  \egroupcharacter						<TEXT>
  	Names for \, %, {, and } of category `other'.

  \inputsafe "TEXT" FILE_					<PARAGRAPH>
  	Do \input FILE if FILE exists, otherwise issue the warning message
  	TEXT ("No file FILE." if "TEXT" omitted) and ignore the request.

  NOTE: The _ after FILE denotes a blank.

----------------------------------------------------------------------
  	-2.8- MISSING FEATURES
----------------------------------------------------------------------

  	* Handling REF argument with \item, \tag, and \footnote.
  	* Handling \nofrills with \Number*-declared COMMANDs.

===========================================================================
	-3- XPPT OPTION SUMMARY
===========================================================================

There are several options available by \input'ing more files.  These
are treated separately for each file:

----------------------------------------------------------------------
  	-3.1- FIXED FORMAT
----------------------------------------------------------------------

  	Fixed format means that the actual line feeds, tabs, etc. in the
  	document matter.

  \input xfixed							<PREAMBLE>
  	Make the following commands available.

  \obeyspacing...\endobeyspacing				<PARAGRAPH>
  	Obeys spaces, tabs, form-feeds, and new-lines within ... (nothing
  	else).

  \lines...\endlines						<PARAGRAPH>
  \numberedlines...\endlines					<PARAGRAPH>
  	... is read line by line and output obeying spacing retained, but
  	without changing the meaning of any other characters.

  \verb C ... C							<OUTER TEXT>
  	... is output normally except that the characters \{}$&#%@~^_ are
  	given category code `other.'  C should be a single character (not one
  	of \{}$&#%@~^_).  This macro can NOT be used in text that is passed
  	as an argument or is in a group: it is \outer (see the TeXbook).

  \verbatim C ... C \endverbatim				<PARAGRAPH>
  \numberedverbatim C ... C \endverbatim			<PARAGRAPH>
  	... is read line by line and output verbatim, i.e., spacing is
  	retained and the AMS-TeX special characters \{}$&#%@~^_ are set as
  	ordinary characters.  C can not be any of \{}$&#%@~^_ ; you should
  	both end and begin ... with a <return>, and C should not appear at
  	the beginning of any line within ... .

  \verbatiminput FILE_						<PARAGRAPH>
  \numberedverbatiminput FILE_					<PARAGRAPH>
  	Input the FILE and output it as if inserted with the appropriate
  	\verbatim...\endverbatim.  NOTE: the _ after FILE is a space.

  NOTES: (1) There is no \linesinput since you can do \lines\input FILE
  \endlines, whereas you should NOT do \verbatim\input FILE \endverbatim!!!
  (2) These functions are all \outer to ensure that they are only used in
  contexts where TeX has not read any of the following such that we may
  change the \catcodes!  (3) The \verbatim-functions only change \catcodes
  of the characters that are used in AMS-TeX (\{}$&#%@~^_).  If you have
  other active characters then they will retain their meaning!

---------------------------------------------------------------------------
  	-3.2- INTERPRET THE FULL ISO LATIN1 (8859-1) INPUT CHARACTER SET
---------------------------------------------------------------------------

  	This file contains activations of characters such that TeX 3.0
  	accepts the full ISO Latin1 (8859-1) input character set.

  \input xlatin1						<PREAMBLE>
  	This will enable the full character set, e.g., for use with input
  	written using an 8-bit editor under X Windows (that uses Latin 1 as
  	the standard character set).

---------------------------------------------------------------------
  	-3.3-	INTERFACE TO RCS (REVISION CONTROL SYSTEM)
---------------------------------------------------------------------

  This option provides an interface to the RCS revision control system
  by Walter F. Tichy.

  \input xrcs							<PREAMBLE>
  	Make the following commands available.

  \RCSdate$...$							<PREAMBLE>
  \RCSrevision$...$						<PREAMBLE>
  	Modify the date and revision of the paper as given by the RCS
  	variables Date and Revision (not inserted above because then RCS
  	would interfere with this explanation).

  \thedate							<COMMAND>
  \theyear							<COMMAND>
  \therevision							<COMMAND>
  \therelease							<COMMAND>
  	These contain the date and revision of this paper.  They default to
  	\today and \empty, but are set by the revision control commands (the
  	release is the first component of the revision).

===========================================================================
  	-4- FIXES FOR THE AMSPPT DOCUMENT STYLE VERSION 2.1
===========================================================================

  	This file contains redefinitions of features in AMSPPT.DOC 2.1
  	that I consider bugs.

  \input pptfixes						<PREAMBLE>
  	Do this immediately after \documentstyle{amsppt} if you wish to use
  	the following corrections to AMSPPT.

  	-4.1- Miscellaneous fixes
  	-4.2- Reference macro fixes
  	-4.3- Insertion macro fixes

---------------------------------------------------------------------------
  	-4.1- MISCELLANEOUS FIXES
---------------------------------------------------------------------------

  	Minor fixes to the AMSPPT style.

  	\Monograph should set \proclaimheadfont@
  				       ^^^^
---------------------------------------------------------------------------
  	-4.2- REFERENCE MACRO FIXES
---------------------------------------------------------------------------

  	\bookinquotes and \paperinquotes should work as described in Joy (2nd
  	edition), p.263.

  	References on the form \paper...\inbook... have been changed to
  	generate "..., in [<editors>,] <title> (\procinfo)..." to allow
  	omission of editors and to avoid having two sets of parenthesis in
  	case they are specified.  Unfortunately this means that we have to
  	modify the \endref macro...

---------------------------------------------------------------------------
  	-4.3- INSERTION MACRO FIXES
---------------------------------------------------------------------------

  	These are fixes to the insertion macros of plain TeX by Walter Neumann
  	<neumann@mps.ohio-state.edu> modified for AMS-TeX.
  	The following are his comments on what is changed:

   Fixes the following problems with plain TeX's handling of \midinsert and
   \topinsert:
  1. An insert that falls at the top of the page is too high: it's
     top is at top-of-page rather than top-of-ink.
  2. Plain uses \bigskip for space around inserts and assumes \bigskip
     is 12pt plus stretch, so \midinsert misbehaves if \bigskipamount
     is changed. This space should be an independent quantity.
  3. Consecutive midinserts that did not float are spaced twice
     as far apart as consecutive topinserts or floated midinserts.
  4. Midinserts can get out of order (see Exercise 15.5 of TeXbook).
  5. \removelastskip fails after a floated insert. This is relevant for
     an insertion before any construction (such as a proclamation in
     plain TeX) that does an explicit or implicit \removelastskip.

  Remaining problem: TeX uses \topskip instead of \baselineskip for the
  first line of a page after any topinserts. With the default values
  of 10pt and 12pt respectively, this gives 2pt less space between a
  topinsert or floated midinsert and following text than between a
  middle insertion and following text. To avoid this use:

  \topskip=\baselineskip


===========================================================================
	-5- LOG
===========================================================================
This log is maintained by RCS.

$Log: XREADME,v $
Revision 1.25  1992/01/28  06:58:52  kris
Many bug fixes, in particular in BibTeX interface.

Revision 1.24  1992/01/24  04:58:16  kris
Bug fixes (mostly in xfixed.doc).

Revision 1.23  1992/01/22  01:16:13  kris
Fixed bugs; README file now generated automatically.

Revision 1.21  1992/01/15  04:22:03  kris
Many bug fixes and some cleaning up...

Revision 1.20  1992/01/13  00:53:15  kris
Extensive changes and reorganisation.
Hopefully the final bets-test :-)

Revision 1.2  1992/01/07 22:13:47  kris
Allow breaks between \cite entries in text.

Revision 1.1  1991/12/31 13:37:03  kris
Based on ppt+ README.
