How to document a expl3 macro using dtx
While you can start form ltxdoc
and 'roll your own', the recommended approach is to use l3doc
, which is the class used the the LaTeX3 team for expl3
itself. This is currently a rather large collection of hacks, but does deal correctly with things like _
in names, and also provides a richer set of documentation environments than ltxdoc
. Regrettably, l3doc
is lacking really comprehensive documentation: as I say, it's not exactly perfect internally! You can typeset l3doc.dtx
to at least get some information, however.
Perhaps the best way to get the hang of things is to take a look at some of the LaTeX3 sources. I'd recommend avoiding l3doc.dtx
itself and probably l3bootstrap.dtx
, l3names,dtx
and l3basics.dtx
as they are atypical: something like l3clist.dtx
is probably a rather better place to look. (As well as the use of l3doc
, the sources show the 'house style' the team have standardised on. We are keen to encourage that as a more general 'LaTeX3 code style': while you might not totally agree with every decision, in the long term it would be good if most LaTeX3 code looks the same irrespective of author, as this will aid with maintenance.)
What I do is use skdoc
(which I've written, although since it's based on ydoc
presumably this'll work with at least ydoc
as well assuming you load expl3
), and issue the following before the implementation part of the documentation:
\ExplSyntaxOn
\cs_set_protected_nopar:Npn\ExplHack{
\char_set_catcode_letter:n{ 58 }
\char_set_catcode_letter:n{ 95 }
}
\ExplSyntaxOff
\ExplHack
This makes the macro
environments (as well as \cs
and friends) read underscores and colons as “letters” (i.e. part of the macro name) as appropriate in LaTeX3 code.