Joseph Wright skrev 2012-06-05 17.52:
> *An additional syntax convention*
>
> What the team feel may be needed is a way to enable LaTeX3 programmers
> to see which functions they are 'allowed' to use from other modules with

Should that "with" have been "without"?

> having to refer at all stages to the documentation. That does not of
> course mean that the documentation should not be written, but that we
> are looking for additional steps and support for good practice.

There is a sort of contradiction here: how can a programmer sensibly make 
use of a function from another module, unless they consult the documentation 
on it to see what it does? So how can there be a problem in the first place?

Well, presumably because the LaTeX tradition has long been to RTFS whenever 
the documentation fails to provide one with an answer, and to consider 
everything reasonably stable as fair game for hacking. What you seek to do 
is have some sort of convention that would make code that violates the 
module boundaries scream out about this to the knowledgable reader. Neither 
more nor less than that, am I right?

> Marking material as 'internal' to a module can be done by picking some
> naming convention which shows this is the case. The team have discussed
> a number of possible approaches, bearing in mind the fact that LaTeX3
> code is in use and that it is therefore important not to make any
> breaking changes in this regard. The convention we propose is use two
> "_" at the beginning of the module to indicate internal material:
>
>    % Public
>    \foo_function:nn
>    \l_foo_variable_tl
>
>    % Internal
>    \__foo_function:nn
>    \l__foo_variable_tl

Two things come to mind about this:

1. Double underscores, to me, suggests "compiler/vendor defined" rather than 
"internal", which is definitely not the signal you want to send. What 
alternatives have been discussed? One that could be used is that Uppercase 
signals private, i.e.

   \foo_Function:nn
   \l_foo_Variable:nn

2. The default that the suggested convention would choose is that of 
"public"; one would have to make an extra effort to mark something as 
private. While public may be the more common case in several of the more 
basic core modules, I very much doubt it would be so in higher level LaTeX3 
programming.

> *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!

>    %<@@=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. 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.

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.

FWIW, an alternative way of embedding extra directives into a .dtx file that 
I have in production is to designate a specific docstrip module as 
containing code that is directives for the stripper. If one picks the very 
crude syntax for "directives" that each codeline in the @@ module sets the 
current @@ replacement then the above could become

%<@@>foo
%<*pkg>
\@@_function:nn   % Will be converted to \__foo_function:nn
\l_@@_variable_tl % Will be converted to \l__foo_variable_tl
%</pkg>
%<@@>bar
%<*pkg>
\@@_function:nn % Will be converted to \__bar_function:nn
%</pkg>
%<@@>
%<*pkg>
\@@_function:nn % Will be extracted unchanged
%</pkg>

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.

Lars Hellström