Sender: |
|
Date: |
Wed, 6 Jun 2012 23:36:52 +0200 |
Reply-To: |
|
Message-ID: |
|
Subject: |
|
MIME-Version: |
1.0 |
Content-Transfer-Encoding: |
7bit |
In-Reply-To: |
|
Content-Type: |
text/plain; charset=ISO-8859-1; format=flowed |
From: |
|
Parts/Attachments: |
|
|
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
|
|
|