Re: scheme function help

[David Kastrup]

"Peter Gentry" <address@hidden> writes:

> This conversation is throwing much light on the difficulty that even
> the computer literate face when trying to learn the Lilypond
> Scheme interface.

By using documentation from 5 years ago with a current version of
LilyPond.  Preceding my work on usability.

I don't consider it fair to judge LilyPond and the work that has been
invested into it in that area on that base.

> In this case the simple addition of a mark is seen to be very complex
> with procedures and arguments that are counter intuitive (or at least
> nowhere near intuitive). Nor are they and their uses fully defined in
> the manuals (I'm sure it is obvious to a developer but confusing to an
> outsider).

Get real.  define-music-function is explained pretty well, and the
function is

addmarkup =
#(define-markup-function (parser location mark music)
  (markup? ly:music?)
  #{ \mark #mark #music #})

which is a dead-simple wrapper not really involving any Scheme
programming, and the obvious way to do this once you have read the
documentation.  If you also want to allow for
\addmarkup \default { c'd' e' f' }, this becomes

#(define-markup-function (parser location mark music)
  ((markup?) ly:music?)
  (if mark
     #{ \mark #mark #music #}
     #{ \mark \default #music #}))

which is more intricate but still a very basic wrapper once you bother
looking up \default and/or optional function arguments.

> Secondly there are apparently several ways to skin the cat and
> contexts that are not immediately obvious.

If you try doing things in a complex manner unnecessarily, possibly
triggered by very old documentation, you can expect complex problems.

> Guidance at the gateway would be a very productive way to spread the
> use of Lilypond beyond highly qualified developers into the more
> mundane world of the everyday user.

So what do you think I have been doing for the last two years?

> None of this is criticism of the project which is a remarkable
> achievment - more a cry from the wilderness for a helping hand to
> newcomers. Actually not so much a helping hand more an appreciation of
> the misconceptions and misunderstandings that plague the tyro.

Try starting with the documentation corresponding to the version you are
using.  The above examples are for the current version, but 2.16 works
almost the same except for requiring $music instead of #music in the
expressions.

And yes, the documentation goes to a lot of effort in order to explain
the details.  And yes, this was awfully documented and awful to use in
2.12, the documentation that the original poster chose to consult.

-- 
David Kastrup