LATEX-L Archives

Mailing list for the LaTeX3 project


Options: Use Classic View

Use Proportional Font
Show Text Part by Default
Condense Mail Headers

Topic: [<< First] [< Prev] [Next >] [Last >>]

Print Reply
Sender: Mailing list for the LaTeX3 project <[log in to unmask]>
Date: Thu, 7 Jun 2012 00:03:49 +0200
Reply-To: Mailing list for the LaTeX3 project <[log in to unmask]>
Message-ID: <[log in to unmask]>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
In-Reply-To: <[log in to unmask]>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
From: Frank Mittelbach <[log in to unmask]>
Parts/Attachments: text/plain (112 lines)
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


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


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
> (, 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


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.