## 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 >>]

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

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