Re: melismaBusyProperties: scheme syntax vs. lily syntax

[David Kastrup]

Thomas Morley <address@hidden> writes:

> 2018-07-16 3:14 GMT+02:00 Carl Sorensen <address@hidden>:
>>
>>
>> On 7/15/18, 6:53 PM, "Simon Albrecht" <address@hidden> wrote:
>>
>>     On 16.07.2018 02:51, Carl Sorensen wrote:
>>     >
>>     > On 7/15/18, 3:29 PM, "lilypond-devel on behalf of David
>>     > Kastrup" <address@hidden on
>>     > behalf of address@hidden> wrote:
>>     >
>>     >      Simon Albrecht <address@hidden> writes:
>>     >
>>     >      > Hello everybody,
>>     >      >
>>     >      > I just noticed that it’s possible to use the LilyPond
>>     >      > symbol list/key
>>     >      > list syntax when setting melismaBusyProperties. However, the doc
>>     >      > string reads
>>     >      >
>>     >      > "A list of properties (symbols) to determine whether a
>>     >      > melisma is playing.
>>     >      > Setting this property will influence how lyrics are
>>     >      > aligned to notes.
>>     >      > For example, if set to @code{'(melismaBusy beamMelismaBusy)},
>>     >      > only manual melismata and manual beams are considered.
>>     >      > Possible values include @code{melismaBusy}, 
>> @code{slurMelismaBusy},
>>     >      > @code{tieMelismaBusy}, and @code{beamMelismaBusy}."
>>     >      >
>>     >      > Would we want to change the first code example to
>>     >      >
>>     >      > @code{melismaBusy,beamMelismaBusy}
>>     >      >
>>     >      > or otherwise suggest the new syntax?
>>     >
>>     >      Feel free to do so, I think.  It's not really a change of syntax
>>     >      specifically for melismaBusyProperties so I'd likely not
>>     > mess with the
>>     >      descriptions when they talk about "symbol list" or whatever.  
>> Instead
>>     >      I'd just change the examples.
>>     >
>>     > I don't think we should change the doc string.  IIUC, the
>>     > property actually is a list. But we can set it using LilyPond
>>     > syntax, as well as Scheme syntax.  So I agree that it should
>>     > shown in the examples, but the docstring should not be
>>     > changed.
>>
>>     What examples do you mean?
>>
>> Apparently, there are none. So I guess that if we want to move in
>> this direction, we should add a docs tagged snippet that shows the
>> property being set.
>>
>> Or alternatively, we should just leave it as is.
>>
>> Thanks,
>>
>> Carl
>
>
> Hi all,
>
> let me hook in here, refering to the more generic topic of this
> thread: "scheme syntax vs. lily syntax"
>
> Meanwhile we have several possibilities where naked scheme-syntax can
> be done by more readable and (hopefully) more userfriendly ly-syntax.
> Things like dotted/comma-separated lists, etc.
> Several macros were introduced as well, `make-engraver` for example.
>
> All very nice. Most of the time.
>
> Though, I remember at least one instance where `make-engraver' failed
> for a very special use-case.
> Then I tried the scheme-list-syntax for engravers and found it worked.
> Asking on the list, David K confirmed a certain limitation in
> `make-engraver`.
> Meanwhile we had eliminated the scheme-list-syntax for engravers from
> our source completely, without having stored some examples of old
> list-syntax-engravers I would have been lost.

To be fair, the doc string of make-engraver is

    "Helper macro for creating Scheme engravers.

    The usual form for an engraver is an association list (or alist)
    mapping symbols to either anonymous functions or to another such
    alist.

    @code{make-engraver} accepts forms where the first element is either
    an argument list starting with the respective symbol, followed by the
    function body (comparable to the way @code{define} is used for
    defining functions), or a single symbol followed by subordinate forms
    in the same manner.  You can also just make an alist pair
    literally (the @samp{car} is quoted automatically) as long as the
    unevaluated @samp{cdr} is not a pair.  This is useful if you already
    have defined your engraver functions separately.

    Symbols mapping to a function would be @code{initialize},
    @code{start-translation-timestep}, @code{process-music},
    @code{process-acknowledged}, @code{stop-translation-timestep}, and
    @code{finalize}.  Symbols mapping to another alist specified in the
    same manner are @code{listeners} with the subordinate symbols being
    event classes, and @code{acknowledgers} and @code{end-acknowledgers}
    with the subordinate symbols being interfaces."

Which is sort of more than was there in forms of explicit documentation
(rather than only example code) for engravers earlier.  If you compare
with the actual macro _code_, you'll find that this doc string contains
a whole lot more information about the details of Scheme engraver
anatomy than the actual macro code (which is not interested in any of
the described names but just maps one structure to another).

> Probably other problems with ly-syntax (replacing scheme-syntax) and
> macros may occur, _if_ they are attempted to be used for something
> they were not designed for.

Well, symbols like violin1 are not LilyPond words.

> So I think we should explain/demonstrate somewhere what these
> syntax/macros are supposed to do/replace in order to give people
> wanting to change/extent/further develop them some more basic hints.
>
> As an example:
>
> foo = 2,4,8
> \void \displayScheme \foo
> => (list 2 4 8)
>
> Would the Extanding Manual be an appropriate place?

I think so.  Seems like "Scheme in LilyPond" would be the right chapter,
but there does not seem to be a lot about equivalencies in it short of
what # and $ do.

For example, things like 2/4 mapping to '(2 . 4) should also be
described there but a cursory glance fails to find them.

-- 
David Kastrup