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
> % Internal
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.
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
> *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!
> \@@_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
\@@_function:nn % Will be converted to \__foo_function:nn
\l_@@_variable_tl % Will be converted to \l__foo_variable_tl
\@@_function:nn % Will be converted to \__bar_function:nn
\@@_function:nn % Will be extracted unchanged
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.