## LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

 Options: Use Forum View Use Monospaced Font Show Text Part by Default Show All Mail Headers Message: [<< First] [< Prev] [Next >] [Last >>] Topic: [<< First] [< Prev] [Next >] [Last >>] Author: [<< First] [< Prev] [Next >] [Last >>]

 Subject: Re: Separating out 'public' and 'internal' functions/variables in LaTeX3 modules From: Frank Mittelbach <[log in to unmask]> Reply To: Mailing list for the LaTeX3 project <[log in to unmask]> Date: Wed, 6 Jun 2012 23:36:52 +0200 Content-Type: text/plain Parts/Attachments: text/plain (97 lines)
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