=============== 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). -----------------------------------------------------------------------------