Debian Codegraph @

texmf-dist/doc/latex/mdwtools/README

raw
1
2 ===============
3
4 M D W T O O L S
5
6 ===============
7
8
9 --- Licence note ---
10
11 mdwtools package release note
12 Copyright (c) 1996 Mark Wooding, except doafter, which is Copyright (c) 1996
13 Peter Schmitt and Mark Wooding.
14
15 These programs are free software; you can redistribute them and/or modify
16 them under the terms of the GNU General Public License as published by
17 the Free Software Foundation; either version 2 of the License, or
18 (at your option) any later version.
19
20 These programs are distributed in the hope that they will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 GNU General Public License for more details.
24
25 You should have received a copy of the GNU General Public License
26 along with these programs; if not, write to the Free Software
27 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
28
29
30 --- What it's all about ---
31
32 This is a bunch of LaTeX 2e packages which have made my life as a LaTeX user
33 easier, so I thought I'd share them. I'm mainly an ARM assembler hacker
34 (which explains why my TeX code looks so horrible), although I have been
35 known to write documentation for programs. This may explain the sort of
36 things these packages do, and where I'm coming from.
37
38
39 --- Licencing ---
40
41 The packages are made available under the GNU General Public Licence (not the
42 usual LaTeX agreement). A copy of this licence is supplied in the file
43 COPYING. You should read this document if you haven't read it already, even
44 if it's just for educational value. I'm not actually sure how good a thing
45 the GNU GPL actually is, so I'm sort of testing the water. The idea that
46 this is how all software should be distributed still fills me with a certain
47 amount of trepidation.
48
49
50 --- What's in the box ---
51
52 You should have received the following files in whatever sort of archive
53 thing this suite came in:
54
55 README -- You've got this file for sure, because it's this one
56 COPYING -- A textual version of the GNU General Public Licence
57 at.dtx -- Documentation and code for `at.sty' package
58 cmtt.dtx -- Documentation and code for `cmtt.sty'package and
59 associated files
60 doafter.dtx -- Documentation and code for `doafter.sty' package; the
61 code is also used in `syntax.sty' and `mdwtab.sty'
62 mdwlist.dtx -- Documentation and code for `mdwlist.sty' package
63 mdwmath.dtx -- Documentation and code for `mdwmath.sty' package
64 mdwtab.dtx -- Documentation and code for `mdwtab.sty' and `mathenv.sty'
65 packages
66 footnote.dtx -- Documentation and code for `footnote.sty' package; the
67 code is used in `mdwtab.sty'
68 sverb.dtx -- Documentation and code for `sverb.stx' package
69 syntax.dtx -- Documentation and code for `syntax.dtx' package
70 mdwtools.ins -- Installation script for all the packages
71 gpl.tex -- LaTeX version of the GNU General Public Licence
72 mdwtools.tex -- Definitions for typesetting the documentation
73
74 If you're missing any of these files, complain at whoever gave the rest of
75 them to you, and get them quickly. However, if you're lucky, you may have
76 received some other files:
77
78 at.sty -- Unpacked `at.sty' package
79 cmtt.sty -- Unpacked `cmtt.sty' package
80 mTTenc.def -- Unpacked encoding definition file for `cmtt.sty'
81 mTTcmtt.fd -- Unpacked font definition file for `cmtt.sty'
82 doafter.sty -- Unpacked `doafter.sty' package for LaTeX
83 doafter.tex -- Unpacked `doafter.tex' package for Plain TeX
84 mathenv.sty -- Unpacked `mathenv.sty' package
85 mdwlist.sty -- Unpacked `mdwlist.sty' package
86 mdwmath.sty -- Unpacked `mdwmath.sty' package
87 mdwtab.sty -- Unpacked `mdwtab.sty' package
88 footnote.sty -- Unpackad `savenot.dty' package
89 sverb.sty -- Unpacked `sverb.sty' package
90 syntax.sty -- Unpacked `syntax.sty' package
91
92 at.dvi -- Typeset documentation for `at.sty'
93 cmtt.dvi -- Typeset documentation for `cmtt.sty' and co.
94 doafter.dvi -- Typeset documentation for `doafter.sty'
95 mdwlist.dtx -- Typeset documentation for `mdwlist.sty'
96 mdwmath.dvi -- Typeset documentation for `mdwmath.sty'
97 mdwtab.dvi -- Typeset documentation for `mdwtab.sty' and `mathenv.sty'
98 footnote.dvi -- Typeset documentation for `footnote.sty'
99 sverb.dvi -- Typeset documentation for `sverb.sty'
100 syntax.dvi -- Typeset documentation for `syntax.sty'
101
102 If you've already got these, then great, because you don't have to generate
103 them. If you haven't, it's not a big deal. You might also have a bunch of
104 files with extensions like `.log', `.aux', `.tmp', `.ilg' and so on. These
105 files are really not at all interesting, and you might as well get rid of
106 them now.
107
108
109 --- What the packages do ---
110
111 Before we can get anywhere, you need to know what the packages do, roughly
112 speaking. Here's a quick rundown:
113
114 at.sty -- Allows you to use `@' as a sort of `command-introducing'
115 character, a bit like `\' is already. This gives you
116 a lot more short command names which you can assign to
117 common constructions. For example, you can set up
118 @/<text>/ as a command to put <text> in italics.
119
120 cmtt.sty -- Provides an `mTT' encoding for the Computer Modern
121 Typewriter font, which solves lots of messy problems.
122
123 doafter.sty -- Provides a TeX programmer's utility
124 \doafter <token> <group>
125 which does the <token> after the group is complete,
126 including any \aftergroup things. The code was originally
127 written by Peter Schmitt in answer to a `challenge' I made
128 on comp.text.tex;I tweaked it a bit to make it work
129 slightly better. doafter.tex is a plain TeX version of
130 the same macro.
131
132 mathenv.sty -- Contains a collection of mathematical environments with
133 a theme of aligning things in columns. There's a
134 rewritten version of `eqnarray' which is much more
135 powerful than the old one, and it gets the spacing right.
136 This package requires `mdwtab.sty' in order to work. It
137 is extracted from `mdwtab.dtx'. In general, the AmS
138 things to a better job, although it seems that the mathenv
139 matrix and script handling environments give prettier
140 results than the AmS equivalents (at least to my eyes).
141
142 mdwlist.sty -- Various list related environments. There's a more
143 versatile `description' environment, and some stuff for
144 making `compacted' lists (with no extra space between
145 items).
146
147 mdwmath.sty -- Contains a few trivial definitions for mathematical
148 things. The main thing is that the \sqrt command for
149 doing square roots has been improved -- there's a \sqrt*
150 command which stops the line being drawn over the formula
151 being square-rooted, and the positioning of the root
152 index (the optional argument) has been improved.
153
154 mdwtab.sty -- A complete ground-up rewrite of LaTeX's `tabular' and
155 `array' environments. Has lots of advantages over
156 the standard version, and over the version in `array.sty'.
157 It works correctly with all the table-related packages in
158 the Tools bundle (longtable, delarray, hhline, tabularx
159 and dcolumn). This package includes most of the code
160 from `doafter.sty' and `footnote.sty' (it doesn't load
161 the packages -- it has its own copies built-in, although
162 you won't waste memory if you do load these packages).
163 To generate `mdwtab.sty', you require `mdwtab.dtx',
164 `doafter.dtx' and `footnote.dtx'; the last two provide
165 the shared code.
166
167 footnote.sty -- Provides commands for saving executing footnotes; the
168 author has noticed several packages which attempt to
169 enable footnotes in tables, all of which eat an extra
170 token list register. This is an attempt to offer shared
171 code to do the job, saving space and effort. It also
172 provides a `footnote' environment which allows verbatim
173 text.
174
175 sverb.sty -- A bunch of macros for doing verbatim things. Required
176 for typesetting all the documentation for the other
177 packages.
178
179 syntax.sty -- A load of commands for describing syntax. There's an
180 environment for typesetting BNF grammars. But best of
181 all, there's a load of commands and environments for
182 drawing syntax diagrams. Required for typesetting all
183 the documentation for the other packages. If you're
184 extracting syntax.sty from syntax.dtx, you also need
185 doafter.dtx.
186
187 With the exception of the dependencies listed above, the packages will all
188 work independently of each other. If you want to typeset the documentation,
189 you'll need `sverb.sty' and `syntax.sty'. Typesetting the documentation
190 isn't essential, although it will probably help if you can see what the
191 various commands actually do.
192
193
194 --- Extracting the packages ---
195
196 If you don't have the various .sty files already, you'll need to extract them
197 from the .dtx files. This requires docstrip.tex, which should be part of
198 your base LaTeX 2e distribution. If you have docstrip vsersion 2.3d, which
199 is available with the December 1995 release of LaTeX, things will go rather
200 faster. If your LaTeX release is much older than this, you should upgrade,
201 because the packages need a fairly new LaTeX anyway. (I could do something
202 about this, but I won't, because I want to encourage everyone to upgrade.)
203
204 If everything's set up correctly, all you should need to do is say
205
206 tex mdwtools.ins
207
208 or
209
210 latex mdwtools.ins
211
212 or whatever incantation is necessary to run TeX or LaTeX on the supplied
213 `mdwtools.ins' file on your system.
214
215 TeX will grind away at the files for a bit, and then say `Done' at you. (This
216 could take a while, so be patient.) You will then have a mdwtools.log file,
217 which you can throw away, and a collection of sparkly new .sty files, which
218 you should put somewhere where TeX can find them easily.
219
220
221 --- Typesetting the documentation ---
222
223 If you want to typeset the documentation for a package, you'll need the
224 `mdwtools.tex' file provided, and the `syntax.sty' and `sverb.sty' packages.
225 You'll also need the `.dtx' file for the package you want documentation on,
226 and any packages it generated.
227
228 For example, if you want documentation on `mathenv.sty', you need:
229
230 mdwtools.tex -- Shared defintions for all the documentation files
231 syntax.sty -- Syntax typesetting commands
232 sverb.sty -- Verbatim text handling commands
233 mathenv.sty -- So the documentation can use it to demonstrate its
234 features
235 mdwtab.sty -- Required by `mathenv.sty'
236 mdwtab.dtx -- The documentation file from which `mathenv.sty' was
237 extracted, and therefore the file which contains the
238 documentation you want to read
239
240 Make sure you've got all the files, and then run LaTeX on the .dtx file you
241 want to read.
242
243 TeX will start hammering away for a very short while, and then stop and ask
244 you whether you want to build the indexing files. Generating index files
245 takes a lot longer (I'd guess that it doubled the amount of time taken to
246 typeset the `.dtx' file) so I don't recommend it unless:
247
248 * you've got a very fast processor, or
249 * you're very interested in how the package works internally, or
250 * you just like everything to be complete, or
251 * you're a masochist.
252
253 Even so, there's no point writing indexing information the first time you
254 run LaTeX on a file, because the table of contents hasn't been created yet,
255 and when you LaTeX the file the second time, all the references will change.
256
257 If you want the index files anyway, type `y' when you're asked. Otherwise,
258 type 'n'. You know you want to type `n' really...
259
260 If you want to do the job properly, you need to run LaTeX a second time
261 to read in the contents table. /This/ is the correct time to turn on
262 indexing, if you really want it.
263
264 If you did build the index files, you should now sort the index by saying
265
266 makeindex -s gind.ist <name>.idx
267
268 where <name> is the same as the name of the `.dtx' file. The `gind.ist' file
269 should have come with LaTeX. Having done this, you should run the `.dtx'
270 file though LaTeX one final time, to insert the formatted index.
271
272 You can now print or preview the generated `.dvi' file using whatever tools
273 you usually use for such things.
274
275
276 --- What changed? ---
277
278 Here's a list of what changed in the various releases.
279
280 Version Changes
281
282 1.00 * First general releases of everything.
283
284
285 1.01 * Fixed typos in various bits of documentation.
286
287 * (mdwtab.sty) Added enhanced \cline command. Added
288 hhline.sty to list of supported table-related packages.
289 (I guess it always worked -- I just forgot about it.)
290 Made some of the section titles a little sillier ;-)
291
292 * (mathenv.sty) Added some new random environments, mainly
293 because I saw some more interesting examples in /The/
294 /TeXbook/ and had an idea... Now support nesting of
295 various environments, albeit rather imperfectly.
296
297 * (at.sty) Made @-commands really properly robust. Fixed
298 some lies in the documentation. Removed some truly insane
299 bits of old code here too. Made package sort of
300 cooperate with amsmath's use of @-commands -- suggestions
301 for improvement welcomed.
302
303 * (mdwtools.tex) Fixed /really/ stupid mistake in which made
304 typesetting the documentation about fifty times slower
305 than it should have been (bashes self on head several
306 times). Changed the structure here a bit too, to handle
307 document classes as well as packages. Made TeX much
308 quieter while it's typesetting the documentation.
309
310 * (sverb.sty) Fixed duff paragraph formatting in listing
311 environment and \verbinput command (due to the `wrong
312 sort' of grouping). (My excuse for missing this one is
313 that my standard document class sets \parskip=0pt.)
314
315 * (mdwtools.ins) Fixed this in line with the documentation
316 which hints that it should work with older docstrips.
317 It's a bit hacky but it works.
318
319
320 1.02 * (gpl.tex) Fixed some bugs which made typesetting go wrong
321 in larger documents. Restructured preamble so that it
322 can be typeset on its own. Put in eplicit item numbers
323 in the enumerate environments, for more obvious conformance
324 to the original.
325
326 * (mdwtab.sty) Lots of changes here, many suggested by
327 David Carlisle (so oodles of thanks to him for taking
328 an interest in my humble hackings). Fixed bugs, including
329 one which put entirely incorrect interline spacing in
330 `p' type columns. Redone the handling of [t] and [b]
331 tables with top and bottom rules, and removed the
332 `\rulefudge' parameter which is no longer necessary.
333 Miscellaneous other changes.
334
335 * (mdwtab.dtx) Tidied up some nastinesses in the
336 documentation, and removed the `\over' commands from the
337 maths demos, to keep certain people happy. Floated a few
338 more of the demonstrations to make page breaking better.
339 There's a danger that some of the demos are drifting too
340 far away from their text, but it's not too bad yet.
341
342 * (syntax.sty) Used \doafter here to fix some colour handling
343 problems.
344
345 * (syntax.sty) Tidied up the `grammar' environment quite a
346 bit (it now uses `\item', rather than trying to emulate it
347 internally), and fixed some vicious bugs in it and some
348 other code.
349
350 * (doafter.sty etc.) A new addition, to make the various
351 packages handle colour properly. Mainly written by
352 Peter Scmitt, actually, I just fiddled with it a little.
353 Then Peter gave me a better version, and I've tried to
354 upgrade this one.
355
356 * (footnote.sty) A new addition, to offer some shared things
357 for handling footnotes. It also enables footnotes in
358 parboxes, which used to be difficult, and provides a
359 `footnote' environment which allows verbatim text.
360
361 * (mdwlist.sty} A new addition, providing miscellanous
362 list-related macros. It's a sort of mixed bag of things
363 I've had lying around various document preambles, combined
364 with some ideas from the Companion.
365
366 * (at.sty) Rewritten command name parser to be much nicer.
367 Added support for digits within @-command names (subject
368 to being enabled by an option). This is in response to
369 requests in comp.text.tex for digits in command names.
370
371 * (mathenv.sty) Totally overhauled the matrix spacing rules.
372 Added `script' environment. Improved numbering things,
373 with `\eqnumber'.
374
375 * (mdwtools.tex) Some minor changes here to fix some buglets.
376 Played with some more float parameters, to discourage
377 float pages a bit more. Then revamped completely, turned
378 into a docced program (although it isn't docstripped),
379 rewritten title generation, and made much more
380 customisable.
381
382
383 1.02a * (mdwtab.sty) Added support for table beautification in
384 longtable. Documented how to do this.
385
386
387 1.03 * (mdwtab.sty) Completely redone the paragraph-cell handling:
388 list environments now work properly inside tables (without
389 funny extra space appearing at the top and bottom). Also
390 fixed a bug in the newline handling, which ignored negative
391 interrow space in the \\ command.
392
393 * (syntax.sty) Changed the underscore handling, and some
394 other bits, to fit in rather better with LaTeX's output
395 encoding system. It's nastier and hackier inside, but it
396 works better with things like the DC fonts. Also stopped
397 re-lowercasing of `~' from escaping and messing everything
398 up for everyone. Improved underscore appearance by
399 lowering it some more.
400
401 * (syntax.sty) Replaced some `2's with `\tw@'s. Added a
402 comment about dvips's inaccurate positioning of rules.
403
404 * (sverb.sty) Made non-* environments build end text from
405 the name of the current environment, rather than having it
406 hardcoded. Also stopped `unignore' environments being
407 a group.
408
409 * (sverb.dtx) Removed some porkies from the documentation.
410
411 * (mdwtab.sty) Fixed some miscellaneous typos. Removed
412 `\rulefudge' from the table of tweakables, because it
413 was withdrawn in release 1.02.
414
415 * (cmtt.dtx) New package, for handling the `cmtt' font
416 better. It introduces a special encoding for the font,
417 and provides a command which allows you to use all the
418 characters without the disadvantages of verbatim text.
419
420 * (other changes) Improved distribution building and
421 testing stuff which you can't see because I'm not
422 releasing it.
423
424
425 1.04 * (syntax.sty) Provided some new commands for playing with
426 interword spacing in `tt' fonts.
427
428 * (doafter.dtx and footnote.dtx) Added some docstrip guards
429 around the meta-comments, so that the charactertable and
430 the GPL header aren't put into other packages.
431 Unfortunately the version of docstrip which understands
432 this hasn't been released yet...
433
434 * RCSified everything, so I can find old revisions, and I'm
435 less likely to destroy everything.
436
437 * (footnote.dtx) Added a check for AMS environments doing
438 measuring passes, to avoid duplicated footnotes. (Spotted
439 by Roberto Bagnara.)
440
441
442 1.05 * (mdwtab.dtx) Fixed stupid bug in paragraph cells which
443 left 1000pt high table rows. (Spotted by Rowland.)
444
445 * (mdwtab.dtx) Fixed horizontal spacing problems with
446 empty paragraph cells.
447
448 * (mdwlist.dtx) Allowed compact lists and resumed lists
449 to pass arguments on to the underlying environments.
450
451 * (syntax.dtx) Fix bug affecting underscore handling in
452 syntax abbreviations.
453
454 --- Future plans ---
455
456 doafter.sty Add Peter Schmitt's testing for implicit/explicit braces,
457 as a package or docstrip option. (This extra testing is
458 a significant chunk of code, and I don't think it's worth
459 burdening the standard version with it. Peter agrees with
460 me.)
461
462 mathenv.sty Do postprocessing on display maths environments to position
463 the equations and equation numbers properly, so they don't
464 overlap (like the AMS environments do, although more
465 robustly). Once this is done, I think I'll have a reasonable
466 case for saying that this provides an alternative to the
467 AMS environments, although quite what the advantage is I
468 don't know: mdwtab.sty isn't exactly small.
469
470 Work is currently `in progress' on this one.
471
472 mdwtab.sty Consider doing postprocessing on tables (yuk) in a blkarray
473 sort of way.
474
475 footnote.sty Merge with Robin Fairbairn's package of the same name. Allow
476 different rules for continued notes (suggested by Donald
477 Arseneau, after a news article by Jonathan Wand).
478
479 New packages I'm currently working on a little something for typesetting
480 poetry properly (centring poems horizontally based on the
481 longest line, etc.), handling footnotes properly, doing
482 line numbering etc. If anyone has any wishes for this,
483 little things a tyro like me ought to know, or knows that
484 it's already done better than I could manage, then let me
485 know.
486
487
488 --- Contacting the author ---
489
490 The author can be reached by email at [email protected]. This is his
491 personal dial-up account, paid for privately, so don't expect replies after
492 five minutes or anything like that.
493
494 If you do have any comments regarding the code, its documentation, or
495 anything else to do with these packages, don't leave me guessing -- let me
496 know. While I won't guarantee to do anything about your comments, chances
497 are that I'll right any wrongs and rescue any damsels in distress (oh, no,
498 wrong spiel).
499
500
501 -----------------------------------------------------------------------------