Joseph Wright skrev 2014-03-30 22.13:
> 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

I think I wanted to allow things like \toks4 as #2, even if I only use it 
with \toks@ as that argument. Hence n rather than N; in any case the 
implementation does not assume a single token.

>   - \harmless_userboolean:nTF  - #1 seems to be a single token,
>     so again N-type

Nope, it is explicitly stated that it also accepts a TF-style conditional as 
#1 (e.g. \IfFileExists{foobar.cfg} or \ifthenelse{<some test>}), so again an n.

>   - \__harmless_quat_split- (etc) - all missing an arg spec, which
>     looks w-type to me

My thinking was that these are "constants" rather than "functions", and for 
that reason have no argspec part. Even if one considers them functions, they 
don't take any arguments, so why would they have a w?

> I'd also suggest the 'sheep and goats' separation of all commands into
> fully expandable or \protected.

Not sure there could only be those two, but I can certainly change some 
\newcommand's into \DeclareRobustCommand's.

> (Note: moving the code to expl3 would require quite a bit of work, but
> that's a different question.)

Beyond the rote substitution of l3names for primitives and 2e core macros, 
is there something particular you think about? (I suspect the unimperative 
coding style could be one issue. ;-)

> 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.

You mean a token with character code 229 (U+00E5) is more canonical than 
\r{a} as encoding of that character? That's actually close to the way 
harmless would do it (under the \HighCharsUnicode setting). For typesetting, 
there is conversely \UnicodeCharUsesChar.

Lars Hellström