## LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

 Options: Use Forum View Use Monospaced Font Show Text Part by Default Show All Mail Headers Message: [<< First] [< Prev] [Next >] [Last >>] Topic: [<< First] [< Prev] [Next >] [Last >>] Author: [<< First] [< Prev] [Next >] [Last >>]

 Subject: The bugs in the doc package From: Lars Hellström <[log in to unmask]> Reply To: Mailing list for the LaTeX3 project <[log in to unmask]> Date: Tue, 18 May 1999 18:01:01 +0200 Content-Type: text/plain Parts/Attachments: text/plain (58 lines)
```I write this because I find it rather remarkable that the bugs in doc.dtx
of the last LaTeX release still hasn't been corrected (or at least not the
corrections being put on CTAN) a good month and a half after the reports
started to arrive. Had it been some other package then maybe it would have
been understandable (understaffed as the LaTeX3 project is often claimed to
be), but the doc package is so central for code development in the TeX
world that I think the negligence tends to being gross.

For those of you who hasn't encountered any of these bugs yet, here are the
ones I know about (in some cases thanks to the LaTeX bugs database, my
acknowledgements to those who reported them):

1. The syntax of \DescribeMacro has been changed; it now reads its argument
while having \catcode`\\=12. Primarily this means that the name of the
macro described must now be surrounded by { and }, but this has also had
the ironic side effect that the doc package documentation is no longer
compatible with the doc package!

There have been some claims that this is really a feature, and I agree it's
not a bad idea per se (even if it makes it a lot harder to write a
\DescribeMacro for \{ and \}), but isn't this exactly the kind of feature
which should have been added as a new command, instead of through changing
an old, especially since it appearently breaks tons of code?

2. There's a typo on code line 395. It reads
|gdef|gtempa{#2}%
(| has catcode 0 at that point), but should most likely be
|gdef|@gtempa{#2}%

3. If a control sequence with an empty name (like \csname\endcsname
generates; bug 1 unfortunately makes almost everything become such a
control sequence since only the backslash is read) is to go into the index,
it causes an error on line 420:
\expandafter\@tempb\@gtempa\relax
because what is stored in \@gtempa is precisely the macro name and \@tempb
is at this point
macro: #1#2\relax ->  <etcetera>
Taking the intended delimiting \relax as #1, \@tempb scans ahead for
another and fails miserably. The direct error can be avoided by appending
an extra \relax to line 420, but the index entries generated will still
become rather weird.

4. Last, and indeed least, the checksum is wrong.

BTW, has ever a case in which the doc checksum facility correctly detected
that code was missing been recorded? It seems to me that by putting the
\Finale in the end of the .dtx file, as is the recommended (by doc.dtx)
practice, the very macro which checks the checksum will itself be missing
whenever there actually is something missing (due to truncation) which
would be noticed on the checksum! Somehow, I don't think that the expected
form of a checksum error report is to mention nothing at all about the
checksum.

Still, I hope it all will be fixed with some speed, now that it has been
dragged into the public (?) and all. :-)

Lars Hellström
```