On 27/03/2014 18:53, Lars Hellström wrote: > My reason for posting about it here on LATEX-L is twofold. For one, I > think it would be a good idea for the expl3 documenting system to > migrate to this more robust foundation, as I seem to recall there being > identifiers here and there in expl3 that the present system utterly > fails to handle correctly. I'll come back to this below, but first I'll address your immediate question :-) > The second, more immediate reason is however > that I'd like a second opinion as to how well I've managed to follow the > expl3 naming conventions; if there is something I misnamed, then it > would be much better to fix it /before/ uploading a v1.0 to CTAN than > after (even if that is mostly for the sake of principles; I don't expect > a huge following anytime soon). I think 'mostly OK' is the verdict. I spot a few places things look wrong: - \harmless_appendto_toks:nn - #2 is a toks, so N-type - \harmless_userboolean:nTF - #1 seems to be a single token, so again N-type - \__harmless_quat_split- (etc) - all missing an arg spec, which looks w-type to me I'd also suggest the 'sheep and goats' separation of all commands into fully expandable or \protected. (Note: moving the code to expl3 would require quite a bit of work, but that's a different question.) On the first point, about code documentation, a few comments seem to be required. First, while code docs are important to those of us writing packages, they are not actually that significant for most LaTeX users. At the moment it's entirely clear that l3doc is a 'series of hacks' which are there to work in 'l3in2e' mode, and which we can fully expect to completely revise if/when we have a proper stand-alone situation. Thus the aim is not to cover everything but to cover enough to allow us to work on other stuff. More broadly, there are big open questions that some of this is linked to. One is LICR-type input. As you'll see when we land our 'new' case changing functions, the team feeling on input methods for *new* code is to stick close to the engines rather than to the LaTeX2e approach. -- Joseph Wright