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: 7bit
Message-ID:  <4FCFCD74.8090507@latex-project.org>
Date:         Wed, 6 Jun 2012 23:36:52 +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

Hi Lars

> 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.

yes that should read "without".

>> 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?

There is no contradiction. People in the TeX world are used to just 
looking at .sty file and modifying and reusing them. As a result there 
are probably not many macros in the LaTeX kernel that aren't used 
somewhere in somebody's code. As a result you can't change/fix anything 
without breaking somebody's code.

In many cases this was a necessity in LaTeX2e but often it was just bad 
style because there was no guidance and because

   using \@item rather than \item when you know you have a [ following 
saves you one expansion ... (certainly important in the early days)

But now it means that one couldn't replace the internal implementation 
of \item without keeping \@item around or break all kind of packages.

That's what this proposal is trying to achieve. We already did this 
"half-heartily" by having some functions ending in _aux but this didn't 
really work well because it makes the names long so many internal 
functions ended up just having normal names again.

> 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?

yes.

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

Yes we did and played with it. Camel case is not working well (for me at 
least).

Given that we already use underscore a single one in front is not making 
a good mark and I don't think that the "compiler/vendor defined" signal 
is an issue.

> 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.

This is true, but not so bad (imho) and it completely goes away if you 
use the suggested docstrip approach.

cheers
frank