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

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

 Re: l3doc, was Re: xparse Lars Hellström <[log in to unmask]> Wed, 2 Sep 2009 17:18:01 +0200 text/plain (70 lines) 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