===============
M D W T O O L S
===============
--- Licence note ---
mdwtools package release note
Copyright (c) 1996 Mark Wooding, except doafter, which is Copyright (c) 1996
Peter Schmitt and Mark Wooding.
These programs are free software; you can redistribute them and/or modify
them 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.
These programs are distributed in the hope that they 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 these programs; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
--- What it's all about ---
This is a bunch of LaTeX 2e packages which have made my life as a LaTeX user
easier, so I thought I'd share them. I'm mainly an ARM assembler hacker
(which explains why my TeX code looks so horrible), although I have been
known to write documentation for programs. This may explain the sort of
things these packages do, and where I'm coming from.
--- Licencing ---
The packages are made available under the GNU General Public Licence (not the
usual LaTeX agreement). A copy of this licence is supplied in the file
COPYING. You should read this document if you haven't read it already, even
if it's just for educational value. I'm not actually sure how good a thing
the GNU GPL actually is, so I'm sort of testing the water. The idea that
this is how all software should be distributed still fills me with a certain
amount of trepidation.
--- What's in the box ---
You should have received the following files in whatever sort of archive
thing this suite came in:
README -- You've got this file for sure, because it's this one
COPYING -- A textual version of the GNU General Public Licence
at.dtx -- Documentation and code for `at.sty' package
cmtt.dtx -- Documentation and code for `cmtt.sty'package and
associated files
doafter.dtx -- Documentation and code for `doafter.sty' package; the
code is also used in `syntax.sty' and `mdwtab.sty'
mdwlist.dtx -- Documentation and code for `mdwlist.sty' package
mdwmath.dtx -- Documentation and code for `mdwmath.sty' package
mdwtab.dtx -- Documentation and code for `mdwtab.sty' and `mathenv.sty'
packages
footnote.dtx -- Documentation and code for `footnote.sty' package; the
code is used in `mdwtab.sty'
sverb.dtx -- Documentation and code for `sverb.stx' package
syntax.dtx -- Documentation and code for `syntax.dtx' package
mdwtools.ins -- Installation script for all the packages
gpl.tex -- LaTeX version of the GNU General Public Licence
mdwtools.tex -- Definitions for typesetting the documentation
If you're missing any of these files, complain at whoever gave the rest of
them to you, and get them quickly. However, if you're lucky, you may have
received some other files:
at.sty -- Unpacked `at.sty' package
cmtt.sty -- Unpacked `cmtt.sty' package
mTTenc.def -- Unpacked encoding definition file for `cmtt.sty'
mTTcmtt.fd -- Unpacked font definition file for `cmtt.sty'
doafter.sty -- Unpacked `doafter.sty' package for LaTeX
doafter.tex -- Unpacked `doafter.tex' package for Plain TeX
mathenv.sty -- Unpacked `mathenv.sty' package
mdwlist.sty -- Unpacked `mdwlist.sty' package
mdwmath.sty -- Unpacked `mdwmath.sty' package
mdwtab.sty -- Unpacked `mdwtab.sty' package
footnote.sty -- Unpackad `savenot.dty' package
sverb.sty -- Unpacked `sverb.sty' package
syntax.sty -- Unpacked `syntax.sty' package
at.dvi -- Typeset documentation for `at.sty'
cmtt.dvi -- Typeset documentation for `cmtt.sty' and co.
doafter.dvi -- Typeset documentation for `doafter.sty'
mdwlist.dtx -- Typeset documentation for `mdwlist.sty'
mdwmath.dvi -- Typeset documentation for `mdwmath.sty'
mdwtab.dvi -- Typeset documentation for `mdwtab.sty' and `mathenv.sty'
footnote.dvi -- Typeset documentation for `footnote.sty'
sverb.dvi -- Typeset documentation for `sverb.sty'
syntax.dvi -- Typeset documentation for `syntax.sty'
If you've already got these, then great, because you don't have to generate
them. If you haven't, it's not a big deal. You might also have a bunch of
files with extensions like `.log', `.aux', `.tmp', `.ilg' and so on. These
files are really not at all interesting, and you might as well get rid of
them now.
--- What the packages do ---
Before we can get anywhere, you need to know what the packages do, roughly
speaking. Here's a quick rundown:
at.sty -- Allows you to use `@' as a sort of `command-introducing'
character, a bit like `\' is already. This gives you
a lot more short command names which you can assign to
common constructions. For example, you can set up
@/<text>/ as a command to put <text> in italics.
cmtt.sty -- Provides an `mTT' encoding for the Computer Modern
Typewriter font, which solves lots of messy problems.
doafter.sty -- Provides a TeX programmer's utility
\doafter <token> <group>
which does the <token> after the group is complete,
including any \aftergroup things. The code was originally
written by Peter Schmitt in answer to a `challenge' I made
on comp.text.tex;I tweaked it a bit to make it work
slightly better. doafter.tex is a plain TeX version of
the same macro.
mathenv.sty -- Contains a collection of mathematical environments with
a theme of aligning things in columns. There's a
rewritten version of `eqnarray' which is much more
powerful than the old one, and it gets the spacing right.
This package requires `mdwtab.sty' in order to work. It
is extracted from `mdwtab.dtx'. In general, the AmS
things to a better job, although it seems that the mathenv
matrix and script handling environments give prettier
results than the AmS equivalents (at least to my eyes).
mdwlist.sty -- Various list related environments. There's a more
versatile `description' environment, and some stuff for
making `compacted' lists (with no extra space between
items).
mdwmath.sty -- Contains a few trivial definitions for mathematical
things. The main thing is that the \sqrt command for
doing square roots has been improved -- there's a \sqrt*
command which stops the line being drawn over the formula
being square-rooted, and the positioning of the root
index (the optional argument) has been improved.
mdwtab.sty -- A complete ground-up rewrite of LaTeX's `tabular' and
`array' environments. Has lots of advantages over
the standard version, and over the version in `array.sty'.
It works correctly with all the table-related packages in
the Tools bundle (longtable, delarray, hhline, tabularx
and dcolumn). This package includes most of the code
from `doafter.sty' and `footnote.sty' (it doesn't load
the packages -- it has its own copies built-in, although
you won't waste memory if you do load these packages).
To generate `mdwtab.sty', you require `mdwtab.dtx',
`doafter.dtx' and `footnote.dtx'; the last two provide
the shared code.
footnote.sty -- Provides commands for saving executing footnotes; the
author has noticed several packages which attempt to
enable footnotes in tables, all of which eat an extra
token list register. This is an attempt to offer shared
code to do the job, saving space and effort. It also
provides a `footnote' environment which allows verbatim
text.
sverb.sty -- A bunch of macros for doing verbatim things. Required
for typesetting all the documentation for the other
packages.
syntax.sty -- A load of commands for describing syntax. There's an
environment for typesetting BNF grammars. But best of
all, there's a load of commands and environments for
drawing syntax diagrams. Required for typesetting all
the documentation for the other packages. If you're
extracting syntax.sty from syntax.dtx, you also need
doafter.dtx.
With the exception of the dependencies listed above, the packages will all
work independently of each other. If you want to typeset the documentation,
you'll need `sverb.sty' and `syntax.sty'. Typesetting the documentation
isn't essential, although it will probably help if you can see what the
various commands actually do.
--- Extracting the packages ---
If you don't have the various .sty files already, you'll need to extract them
from the .dtx files. This requires docstrip.tex, which should be part of
your base LaTeX 2e distribution. If you have docstrip vsersion 2.3d, which
is available with the December 1995 release of LaTeX, things will go rather
faster. If your LaTeX release is much older than this, you should upgrade,
because the packages need a fairly new LaTeX anyway. (I could do something
about this, but I won't, because I want to encourage everyone to upgrade.)
If everything's set up correctly, all you should need to do is say
tex mdwtools.ins
or
latex mdwtools.ins
or whatever incantation is necessary to run TeX or LaTeX on the supplied
`mdwtools.ins' file on your system.
TeX will grind away at the files for a bit, and then say `Done' at you. (This
could take a while, so be patient.) You will then have a mdwtools.log file,
which you can throw away, and a collection of sparkly new .sty files, which
you should put somewhere where TeX can find them easily.
--- Typesetting the documentation ---
If you want to typeset the documentation for a package, you'll need the
`mdwtools.tex' file provided, and the `syntax.sty' and `sverb.sty' packages.
You'll also need the `.dtx' file for the package you want documentation on,
and any packages it generated.
For example, if you want documentation on `mathenv.sty', you need:
mdwtools.tex -- Shared defintions for all the documentation files
syntax.sty -- Syntax typesetting commands
sverb.sty -- Verbatim text handling commands
mathenv.sty -- So the documentation can use it to demonstrate its
features
mdwtab.sty -- Required by `mathenv.sty'
mdwtab.dtx -- The documentation file from which `mathenv.sty' was
extracted, and therefore the file which contains the
documentation you want to read
Make sure you've got all the files, and then run LaTeX on the .dtx file you
want to read.
TeX will start hammering away for a very short while, and then stop and ask
you whether you want to build the indexing files. Generating index files
takes a lot longer (I'd guess that it doubled the amount of time taken to
typeset the `.dtx' file) so I don't recommend it unless:
* you've got a very fast processor, or
* you're very interested in how the package works internally, or
* you just like everything to be complete, or
* you're a masochist.
Even so, there's no point writing indexing information the first time you
run LaTeX on a file, because the table of contents hasn't been created yet,
and when you LaTeX the file the second time, all the references will change.
If you want the index files anyway, type `y' when you're asked. Otherwise,
type 'n'. You know you want to type `n' really...
If you want to do the job properly, you need to run LaTeX a second time
to read in the contents table. /This/ is the correct time to turn on
indexing, if you really want it.
If you did build the index files, you should now sort the index by saying
makeindex -s gind.ist <name>.idx
where <name> is the same as the name of the `.dtx' file. The `gind.ist' file
should have come with LaTeX. Having done this, you should run the `.dtx'
file though LaTeX one final time, to insert the formatted index.
You can now print or preview the generated `.dvi' file using whatever tools
you usually use for such things.
--- What changed? ---
Here's a list of what changed in the various releases.
Version Changes
1.00 * First general releases of everything.
1.01 * Fixed typos in various bits of documentation.
* (mdwtab.sty) Added enhanced \cline command. Added
hhline.sty to list of supported table-related packages.
(I guess it always worked -- I just forgot about it.)
Made some of the section titles a little sillier ;-)
* (mathenv.sty) Added some new random environments, mainly
because I saw some more interesting examples in /The/
/TeXbook/ and had an idea... Now support nesting of
various environments, albeit rather imperfectly.
* (at.sty) Made @-commands really properly robust. Fixed
some lies in the documentation. Removed some truly insane
bits of old code here too. Made package sort of
cooperate with amsmath's use of @-commands -- suggestions
for improvement welcomed.
* (mdwtools.tex) Fixed /really/ stupid mistake in which made
typesetting the documentation about fifty times slower
than it should have been (bashes self on head several
times). Changed the structure here a bit too, to handle
document classes as well as packages. Made TeX much
quieter while it's typesetting the documentation.
* (sverb.sty) Fixed duff paragraph formatting in listing
environment and \verbinput command (due to the `wrong
sort' of grouping). (My excuse for missing this one is
that my standard document class sets \parskip=0pt.)
* (mdwtools.ins) Fixed this in line with the documentation
which hints that it should work with older docstrips.
It's a bit hacky but it works.
1.02 * (gpl.tex) Fixed some bugs which made typesetting go wrong
in larger documents. Restructured preamble so that it
can be typeset on its own. Put in eplicit item numbers
in the enumerate environments, for more obvious conformance
to the original.
* (mdwtab.sty) Lots of changes here, many suggested by
David Carlisle (so oodles of thanks to him for taking
an interest in my humble hackings). Fixed bugs, including
one which put entirely incorrect interline spacing in
`p' type columns. Redone the handling of [t] and [b]
tables with top and bottom rules, and removed the
`\rulefudge' parameter which is no longer necessary.
Miscellaneous other changes.
* (mdwtab.dtx) Tidied up some nastinesses in the
documentation, and removed the `\over' commands from the
maths demos, to keep certain people happy. Floated a few
more of the demonstrations to make page breaking better.
There's a danger that some of the demos are drifting too
far away from their text, but it's not too bad yet.
* (syntax.sty) Used \doafter here to fix some colour handling
problems.
* (syntax.sty) Tidied up the `grammar' environment quite a
bit (it now uses `\item', rather than trying to emulate it
internally), and fixed some vicious bugs in it and some
other code.
* (doafter.sty etc.) A new addition, to make the various
packages handle colour properly. Mainly written by
Peter Scmitt, actually, I just fiddled with it a little.
Then Peter gave me a better version, and I've tried to
upgrade this one.
* (footnote.sty) A new addition, to offer some shared things
for handling footnotes. It also enables footnotes in
parboxes, which used to be difficult, and provides a
`footnote' environment which allows verbatim text.
* (mdwlist.sty} A new addition, providing miscellanous
list-related macros. It's a sort of mixed bag of things
I've had lying around various document preambles, combined
with some ideas from the Companion.
* (at.sty) Rewritten command name parser to be much nicer.
Added support for digits within @-command names (subject
to being enabled by an option). This is in response to
requests in comp.text.tex for digits in command names.
* (mathenv.sty) Totally overhauled the matrix spacing rules.
Added `script' environment. Improved numbering things,
with `\eqnumber'.
* (mdwtools.tex) Some minor changes here to fix some buglets.
Played with some more float parameters, to discourage
float pages a bit more. Then revamped completely, turned
into a docced program (although it isn't docstripped),
rewritten title generation, and made much more
customisable.
1.02a * (mdwtab.sty) Added support for table beautification in
longtable. Documented how to do this.
1.03 * (mdwtab.sty) Completely redone the paragraph-cell handling:
list environments now work properly inside tables (without
funny extra space appearing at the top and bottom). Also
fixed a bug in the newline handling, which ignored negative
interrow space in the \\ command.
* (syntax.sty) Changed the underscore handling, and some
other bits, to fit in rather better with LaTeX's output
encoding system. It's nastier and hackier inside, but it
works better with things like the DC fonts. Also stopped
re-lowercasing of `~' from escaping and messing everything
up for everyone. Improved underscore appearance by
lowering it some more.
* (syntax.sty) Replaced some `2's with `\tw@'s. Added a
comment about dvips's inaccurate positioning of rules.
* (sverb.sty) Made non-* environments build end text from
the name of the current environment, rather than having it
hardcoded. Also stopped `unignore' environments being
a group.
* (sverb.dtx) Removed some porkies from the documentation.
* (mdwtab.sty) Fixed some miscellaneous typos. Removed
`\rulefudge' from the table of tweakables, because it
was withdrawn in release 1.02.
* (cmtt.dtx) New package, for handling the `cmtt' font
better. It introduces a special encoding for the font,
and provides a command which allows you to use all the
characters without the disadvantages of verbatim text.
* (other changes) Improved distribution building and
testing stuff which you can't see because I'm not
releasing it.
1.04 * (syntax.sty) Provided some new commands for playing with
interword spacing in `tt' fonts.
* (doafter.dtx and footnote.dtx) Added some docstrip guards
around the meta-comments, so that the charactertable and
the GPL header aren't put into other packages.
Unfortunately the version of docstrip which understands
this hasn't been released yet...
* RCSified everything, so I can find old revisions, and I'm
less likely to destroy everything.
* (footnote.dtx) Added a check for AMS environments doing
measuring passes, to avoid duplicated footnotes. (Spotted
by Roberto Bagnara.)
1.05 * (mdwtab.dtx) Fixed stupid bug in paragraph cells which
left 1000pt high table rows. (Spotted by Rowland.)
* (mdwtab.dtx) Fixed horizontal spacing problems with
empty paragraph cells.
* (mdwlist.dtx) Allowed compact lists and resumed lists
to pass arguments on to the underlying environments.
* (syntax.dtx) Fix bug affecting underscore handling in
syntax abbreviations.
--- Future plans ---
doafter.sty Add Peter Schmitt's testing for implicit/explicit braces,
as a package or docstrip option. (This extra testing is
a significant chunk of code, and I don't think it's worth
burdening the standard version with it. Peter agrees with
me.)
mathenv.sty Do postprocessing on display maths environments to position
the equations and equation numbers properly, so they don't
overlap (like the AMS environments do, although more
robustly). Once this is done, I think I'll have a reasonable
case for saying that this provides an alternative to the
AMS environments, although quite what the advantage is I
don't know: mdwtab.sty isn't exactly small.
Work is currently `in progress' on this one.
mdwtab.sty Consider doing postprocessing on tables (yuk) in a blkarray
sort of way.
footnote.sty Merge with Robin Fairbairn's package of the same name. Allow
different rules for continued notes (suggested by Donald
Arseneau, after a news article by Jonathan Wand).
New packages I'm currently working on a little something for typesetting
poetry properly (centring poems horizontally based on the
longest line, etc.), handling footnotes properly, doing
line numbering etc. If anyone has any wishes for this,
little things a tyro like me ought to know, or knows that
it's already done better than I could manage, then let me
know.
--- Contacting the author ---
The author can be reached by email at mdw@excessus.demon.co.uk. This is his
personal dial-up account, paid for privately, so don't expect replies after
five minutes or anything like that.
If you do have any comments regarding the code, its documentation, or
anything else to do with these packages, don't leave me guessing -- let me
know. While I won't guarantee to do anything about your comments, chances
are that I'll right any wrongs and rescue any damsels in distress (oh, no,
wrong spiel).
-----------------------------------------------------------------------------
Generated by dwww version 1.15 on Fri Jun 28 03:58:15 CEST 2024.