Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v929.2)
Message-ID:  <9A98C2E5-6170-4AA4-9E26-CCB96A234D76@gmail.com>
Date:         Tue, 25 Nov 2008 00:51:38 +1030
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender: Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From: Will Robertson <wspr81@GMAIL.COM>
Subject: Documenting LaTeX3 packages (l3doc)
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
Precedence: list
Status: R

Hello,

Packages (or "modules") in the expl3 bundles use the l3doc class for  
documentation in the tradition of ltxdoc. Up until now, l3doc was  
provided as a straight .cls file, which was in a bit of a mess.

This evening I was a little tired, so rather than attempting to write  
any actual code (or work on my thesis), I bundled l3doc.cls into a  
proper .dtx file and tidied it up somewhat. It's now a bit more  
readable, and I managed to remove some code that was duplicated  
elsewhere or was otherwise not really being used.

One maybe big change, though: it now loads the full expl3 suite and  
declares itself as an "ExplClass". It doesn't actually use much LaTeX3  
code, yet, but this is a change from some time ago when the  
documentation for the LaTeX3 code could still be compiled using LaTeX2e.

If there's any problem with this, please let me know and I'll reverse  
my decision.

***

Meanwhile, if any members of this list would like to volunteer with  
maintaining this class, it would be wonderful to create a Franken- 
monster of l3doc, hypdoc, xdoc, and gmdoc. What little time I have  
available now I'm spending on the expl3 test suite, so I suspect  
without outside help this class will remain a patchwork of hacked- 
together code to support whatever markup we happen to want/need while  
writing the expl3 modules.

***

Before I finish this off, I just wanted to mention an extension to the  
{macro} environment that I would like some feedback on. The  
implementation in l3doc is absolutely terrible and needs improvement,  
but the idea is to be able to write
   \begin{macros}{\q_nil,\q_stop,\q_no_value}
etc., and finish it off with a single
   \end{macros}
statement.

This will improve the readability of some of the expl3 code immensely;  
there are sections of that code where there are, seemingly, scores of  
adjacent \end{macro} lines.

Can anyone see any problems if I start changing the expl3 modules to  
use this new markup?

***

Best regards,
Will