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:
>> To tell the extended l3docstrip program what is the appropriate
>> replacement for "@@", an additional guard-like line is also required:
>> \@@_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!
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.
>> \@@_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
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.