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

#### View:

 Message: [ First | Previous | Next | Last ] By Topic: [ First | Previous | Next | Last ] By Author: [ First | Previous | Next | Last ] Font: Proportional Font

Subject:

Re: Separating out 'public' and 'internal' functions/variables in LaTeX3 modules

From:

Date:

Wed, 6 Jun 2012 23:36:52 +0200

Content-Type:

text/plain

Parts/Attachments:

 text/plain (96 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