Joseph Wright skrev:
> I'd imagine that the code needs a careful overhaul at some stage, as
> things are very much a mish-mash at the the moment. However, that
> depends on what we want, as you say. For example, the gmdoc approach of
> not needing \begin{macrocode} ... \end{macrocode} is interesting: I
> wonder if it makes it easier for new users to write documented files?

I've found that an advantage of having an explicit environment around 
blocks of codelines is that this environment can be varied according to 
the type of code. For single-language projects that is perhaps not so 
important, but for mixed-language projects it can be used to improve 
the code typography. Also, one can skip the expensive code indexing 
when typesetting for languages that doesn't have a TeX-style \ 
character in front of every keyword.

It's another matter that doc's macrocode is perhaps not the friendliest 
of environments, requiring exactly four spaces between % and 
\end{macrocode} (might it be that this originates in a preferrence of 
Frank's for an environment indentation step of 3 spaces?) since it uses 
the same end-detection mechanism as verbatim. A perfectly workable 
alternative (that I've used in the tcl environment of the tclldoc 
package) is to mostly restore normal LaTeX catcodes after a % at the 
beginning of a line, so that the \end can be a normal end of 
environment (this also allows users to define shorter aliases of the 
environment name).

Having looked a bit at gmdoc today, I must say the games played there 
with active line-ends throughout the document and special escapes for 
breaking command arguments over several lines seem most worrying. (Is 
it even possible in gmdoc to have a linebreak between two arguments of 
a command?) If the general direction in LaTeX3 is to have less 
\catcode-tricks and active characters, then it would be a strange move 
to rely more on them in the LaTeX3 documentation...


Manuel Pégourié-Gonnard skrev:
> > and I find Paul Isambert's CodeDoc very nice
> > which extracts package code while typesetting the documentation.
> > 
> Well, I don't like this very much: I prefer package code to be the primary
> content 

Package code as primary content has the disadvantage of restricting you 
to one "target file" at a time. When having to make two pieces of 
software communicate with each other, it can be much better to 
interleave the code producing output with the code that then has to 
parse this output.

> and documentation to be extracted from comments. I find it much easier
> for changing the code and testing it without needing ot extract it first. (Same
> problem as dtx.)

For what it's worth, I have for about a decade been using an add-on to 
my text editor that lets me select a piece of code in a .dtx file and 
then press a key (well, a modifier and a key) to have the comment lines 
stripped out and the whole thing sent to an interpreter for evaluation; 
this makes testing small fixes extremely convenient, and it wasn't all 
that difficult to implement.

I'd have to admit I don't use it for developing LaTeX code though; the 
reason for this being that TeX tends to operate more as a batch utility 
than as an interactive application, so by the time I've corrected the 
bug there usually isn't anything I can sent the corrected definition to 
anymore. On the other hand, a simple Makefile should go a long way 
towards automating extraction: run your test as "make mytest", and make 
sure the dependencies of mytest.tex on .sty and of .sty on .dtx are 
explicit.

Lars Hellström