User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:12.0) Gecko/20120428
            Thunderbird/12.0.1
MIME-Version: 1.0
References: <4FCE2B42.2090006@morningstar2.co.uk>
            <4FCFC6D7.20806@residenset.net>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 8bit
Message-ID:  <4FCFD3C5.5050309@latex-project.org>
Date:         Thu, 7 Jun 2012 00:03:49 +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: Frank Mittelbach <frank.mittelbach@LATEX-PROJECT.ORG>
Subject: Re: Separating out 'public' and 'internal' functions/variables in LaTeX3 modules
To: LATEX-L@listserv.uni-heidelberg.de
In-Reply-To:  <4FCFC6D7.20806@residenset.net>
Precedence: list
Status: R

Am 06.06.2012 23:08, schrieb Lars Hellström:
>> *Extending DocStrip*
>>
>> The 'two underscore' convention can of course be used directly in code.
>> However, as it extends the name of every code-level name, this may not
>> be desirable. To support this further, we have also explored the idea of
>> extending DocStrip such that a 'marker' can be used for internal
>> material, such that this can be replaced by the "__foo" part.
>>
>> The approach that we have taken for this is to use "@@" as the indicator
>> for internal code:
>>
>>    \@@_function:nn
>>    \l_@@_variable_tl
>>
>> To tell the extended l3docstrip program what is the appropriate
>> replacement for "@@", an additional guard-like line is also required:
>>
>>    %<@@=foo>
>>    \@@_function:nn   % Will be converted to \__foo_function:nn
>>    \l_@@_variable_tl % Will be converted to \l__foo_variable_tl
>
> Are these examples exact or handwaved? It looks as though @@ magically
> expands to either __foo or _foo depending on context!

magic :-)

The current implementation actually implements the following 
transformations while l3docstripping:

  __@@   -> __foo
   _@@   -> __foo
    @@   -> __foo

in that order. The first one could probably be dropped. I asked for it 
because I thought initially that even with the @@ one might want to write

\__@@_bar:nn

to indicate an internal function in a dtx file. But using this the code 
reads well enough with just

\@@_bar:nn

So that one cuold probably be dropped, although it doesn't hurt.

For variables \l_@@_bar_int just reads better than \l@@_bar_int which is 
why the second transformation is there.


>
>>    %<@@=bar>
>>    \@@_function:nn % Will be converted to \__bar_function:nn
>>
>>    %<@@=>
>>    \@@_function:nn % Will be extracted unchanged
>>
>> (It is important to note that this 'extended DocStrip' idea additional
>> to the idea of an 'internal' syntax.)
>
> An interesting benefit of this could be that if one steals a bit of code
> from some other package, then it will automatically be localised to
> one's own namespace.

It also allows you to directly execute the code even with @@ inside as 
long as you don't try to do this with more than one module name at the 
same time. For example I'm currently writing some code for a new module 
in a different window and write it directly into the .sty file and not 
bother about docstripping at all

> On the other hand, I fear that you may be opening
> up an avenue of feature creep here. If you introduce @@ today, then
> someone will probably want @1@ and @2@ in a year or so.

We intend to ship l3docstrip rather than extending docstrip.tex. I think 
such feature creep can be avoided.


> Also, as someone who is heavily using, and even porting
> (http://tcllib.sourceforge.net/doc/docstrip.html), docstrip with other
> languages, I must say I am more than a bit worried by the idea of making
> assignments to @@ part of the guard expression syntax; that feels like
> extending them into something they're not supposed to be.

open to debate I guess. What is important for me is that the 
transformation rule is part of the documentation which suggests some 
sort of guard notation. But yes, one could think about placing it in the 
docstrip.ins file instead.

We started out with

%<module=coffins>

but in the end the feeling was the simple <@@=foo> actually works better.

Also my expectation is that you do not turn those things one and off 
(except perhaps in the kernel once the currently separated files are 
partly or fully joined together).

So normally there will be a single line at the beginning stating the 
module name to be used in place of @@.

> Other approaches I would find preferable to %<@@=foo> is to use %%%
> lines (as an homage to mft) or explicit commands in the .ins file; after
> all, most source files don't contain code for multiple l3-modules.

To be honest I don't like that much but perhaps this is something one 
just needs getting used to.

'night
frank