User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; sv-SE; rv:1.9.2.28)
            Gecko/20120306 Thunderbird/3.1.20
MIME-Version: 1.0
References: <533473A9.3020401@residenset.net>
            <53387AD3.4060902@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Message-ID:  <533965E4.2060205@residenset.net>
Date:         Mon, 31 Mar 2014 14:56:04 +0200
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: =?ISO-8859-1?Q?Lars_Hellstr=F6m?= <Lars.Hellstrom@RESIDENSET.NET>
Subject: Re: harmless package public beta
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <53387AD3.4060902@morningstar2.co.uk>
Precedence: list
Content-Transfer-Encoding: quoted-printable
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

Joseph Wright skrev 2014-03-30 22.13:
> 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 bein=
g
>> 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 t=
he
>> 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 expe=
ct
>> a huge following anytime soon).
>
> I think 'mostly OK' is the verdict. I spot a few places things look wro=
ng:
>
>   - \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=
=20
with \toks@ as that argument. Hence n rather than N; in any case the=20
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=20
#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 f=
or=20
that reason have no argspec part. Even if one considers them functions, t=
hey=20
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=20
\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=
,=20
is there something particular you think about? (I suspect the unimperativ=
e=20
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 w=
e
> 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=20
\r{a} as encoding of that character? That's actually close to the way=20
harmless would do it (under the \HighCharsUnicode setting). For typesetti=
ng,=20
there is conversely \UnicodeCharUsesChar.

Lars Hellstr=F6m