User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:24.0)
            Gecko/20100101 Thunderbird/24.4.0
MIME-Version: 1.0
References: <533473A9.3020401@residenset.net>
Content-Type: text/plain; charset=ISO-8859-1
Message-ID:  <53387AD3.4060902@morningstar2.co.uk>
Date:         Sun, 30 Mar 2014 21:13:07 +0100
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: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: harmless package public beta
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <533473A9.3020401@residenset.net>
Precedence: list
Content-Transfer-Encoding: quoted-printable
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

On 27/03/2014 18:53, Lars Hellstr=F6m 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.=20

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 th=
e
> 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 expec=
t
> 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