Re: Email from Phil's patchy

[David Kastrup]

Marc Hohl <address@hidden> writes:

> Am 29.07.2012 08:12, schrieb David Kastrup:
>> "Phil Holmes" <address@hidden> writes:
>>
>>> Sorry, Marc.  To do this completely, you will need to add the changed
>>> file to snippets/new.  The files in snippets get over-written when we
>>> import from the LSR, so this update would be lost.  However, to make
>>> current git compile, you do also need to keep this change in snippets.
>>>
>>> I realise this isn't completely straightforward, but that's the way
>>> it is...
>> I repeat: why change all the function names of functions with a public
>> interface in the first place when they have the same functionality?
>> Without a convert-ly rule, this will break user code.  I cited some user
>> quote on the mailing list that will also break.
>>
> I misunderstood the ly: convention in function names.

It is used inconsistently.  It is _required_ (or possibly was at some
point of time, I don't quite remember) for LY_DEFINE.

At a point of time where pretty much everything concerning LilyPond
internal operation was done in C++, it may have had some correlation
with functionality and/or mangling.

But there is really very little sense in us having predicates ly:music?
as opposed to markup? since the user could care less what language some
functionality is, or has been, implemented in, possibly at some point in
history.

Personally, I would think that pretty much everything that looks like a
Scheme interface to a C++ callback (namely containing :: in its name)
should likely have the ly: prefix to preserve some predictability, but
it would appear that this train left station a long time ago.

We also have the situation that we autoextract documentation from
functions defined using LY_DEFINE into the manual (probably the main
incentive to have LY_DEFINE) The same is not done for functions defined
in Scheme as far as I can tell.

But the functions we are talking about were defined with some *CALLBACK*
macro, I think, and not documented anyway.

So it is an inconsistent historical mess we are dealing with here.  It
would be nice to provide some guarantees, like "everything starting with
ly: has a documentation in the internals manual", but those guarantees
should not be tied into the implementation language: that is a line
irrelevant to the user.

Somewhat more relevant would be "don't expect to change this in
mid-session or at all since other callers might have memoized the
location or called it directly".  However, LilyPond code memoizes a lot,
never mind the ly: prefix.

> I renamed the concerned definitions and am currently doing make and
> make doc.
> The changes in Documentation/snippets were reverted.
>
> If make doc succeeds, I'll upload another patch.

To me, I think for drop-in exported-function-by-function replacements,
that is the sanest way to proceed since for the caller, nothing has
changed.

But at one point of time, we need to put down some explicit policies
here as well and come up with good guidelines users and developers can
depend on.  And "implementation language" is a terrible criterion for a
user-visible distinction in interfaces.

In C, the equivalent would be to have to write
extern "FORTRAN"
not just in the respective headers of a library, but also for _every_
_single_ function call.  Now function call prefixes in naming are not
unusual, but they are ordered according to library, not according to
implementation language.  And I don't need yet_another_prefix if the
function has been rewritten in assembly language.

Now it is true that we probably did not have a formal discussion of this
in any rate, and you are probably quite keeping with some sort of
de-facto standard and are in the unlucky position of standing next when
I am waking up to some problem wildly thrashing my arms.

Sorry for that.

We'll likely need something better than a raving core programmer as a
guideline.  In the meantime, I consider it a good idea for drop-in
replacements of public interfaces to keep the name, or the drop-in idea
is no longer valid, meaning that it gets much harder to do comparisons
of before/after when necessary, and we get a user-visible
incompatibility that serves no discernible purpose.

-- 
David Kastrup