Sun, 30 Mar 2014 21:13:07 +0100
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
> 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.