My tex IDE is TeXShop, and the trouble with editing large .dtx files with doc comments is that it doesn’t automatically tag the section commands that are commented out. Normally that’s a Good Thing but it makes it hard to navigate in this usage.

The idea of reusable information certainly came up. I think at the moment the LaTeX3 team have other things to think about, but its not forgotten. There’s probably a need to try to sketch out some very general “desirables” and then work from there, rather than starting with what is around and trying to modify it. Perhaps once we get a bit further on with the lower level LaTeX3 stuff, this might get revisited.

Joseph

After some experimentation I think I found a viable way of incorporating a regular document inside a .dtx file. The trick is to use the comment environment:

% \begin{comment}
%
\documentclass{ltxdoc}
\usepackage{verbatim,foo,bar}
\begin{document}
User interface documentation goes here
\DocInput{\jobname.dtx}% code documentation
\end{document}
%
% \end{comment}

As for the successor to dtx, I would like it to be (re)usable beyond paper output. To give an example of what I mean by that: LEd editor has a very nice feature of displaying syntax hints for commands. This is accomplished by special definition files that have to be prepared for each and every package. If one could extract this kind of information directly from the package documentation, then the whole process could be automated and all packages would benefit from the same level of support without any extra work.

There are other approaches that don’t require writing code as comments. The problem is that none of them are as widespread as the dtx format. (We had some discussion about the pros and cons of various approaches on the LaTeX3 mailing list. Some thought is probably needed to find the “best” way to create a successor to the current system.) I’d point out that a lot of editors (Emacs, TeXworks and WinEdt, at least) can automatically start each line correctly.

As I’ve said, I got the basic form of the dtx I’ve explained from Will! If he fancies adding the code and explanation to his gallery, I’d be quite happy.

By the way, any things that you’d like more on? I currently have two or three more posts in mind.

Joseph

One feature that I’m not so fond of in .dtx format is writing user documentation as comments. This is fine for documenting the implementation but quite awkward for longer stretches of text such as description of the user interface.

Anyway, I think that have you a lot of good information in these .dtx series already, enough for a nice tutorial. Together with your model .dtx file this could make a nice addition to Will’s dtxgallery (just a thought .

I’m looking forward to the rest of the series.