Re: Bleeding edge documentation

[Nicolas Sceaux]

Graham Percival <address@hidden> writes:

> Chapter 11 (scheme stuff) has been extensively changed.  Is any of the
> material in 11.6 still accurate / relevant / useful?
> http://percival-music.ca/Documentation/user/lilypond/OLD-STUFF.html


11.1.1 Overview of music functions

The parser and location arguments may be explained here.

pair? is the type predicate for pairs of anything, not just
numbers. Maybe it could be mentionned that the list is not exhaustive.

11.1.2 Simple substitution functions

tempoMark: a string argument can be written without the sharp. This
looks cleaner: \tempoMark "Allegro" #3.0
Also it's usual, for instance in the case of markup commands, to have
the integer argument before the other. Otherwise, if the string is very
long, the number would be lost after.

tempoMark = 
#(define-music-function (parser location padding marktext)
                                         (number? string?)
  ...
\tempoMark #3.0 "Allegro"

11.2.1 Input variables and Scheme

  #(define (nopc)
    (ly:set-option 'point-and-click #f))
  ...
  #(nopc)

This example could be used in the Music function section, to introduce
void music functions. The style is more consistent using a \nopc music
function instead of a #(nopc) scheme form.

  noPointAndClick =
  #(define-music-function (parser location) ()
     (ly:set-option 'point-and-click #f)
     (make-music 'SequentialMusic 'void #t))
  ..
  \noPointAndClick %% disable point and click

A music function has to return a music expression: that's why the form
that is returned is the (make-music ...). With its 'void property set to
#t, the parser is told to actually disregard this returned music
expression. Thus, the important part of the void music function is the
processing done by the function, not the music expression that is
returned.

11.3.1 Displaying music expressions

Perhaps, the output of the \displayMusic example could be explained a
bit. The output, left verbatim first, may be reformatted to show how
properties and their values are paired:

(make-music 'SequentialMusic
  'elements (list (make-music 'EventChord
                    'elements (list (make-music 'NoteEvent
                                      'duration (ly:make-duration 2 0 1 1)
                                      'pitch (ly:make-pitch 0 0 0))
                                    (make-music 'AbsoluteDynamicEvent
                                      'text "f")))))

- A { ... } music sequence has the name SequentialMusic, and its inner
  expressions are stored as a list in its 'elements property;
- a note is represented as an EventChord expression, containing a
  NoteEvent object (storing the duration and pitch properties) and the
  ornementations, here an AbsoluteDynamicEvent with a "f" text property.

Between that section and the following one, the functions used to access
and set music properties may be introduced.

  someNote = c'
  \displayMusic \someNote

  % ==> (make-music
  %       'EventChord
  %       'elements
  %       (list (make-music
  %               'NoteEvent
  %               'duration
  %               (ly:make-duration 2 0 1 1)
  %               'pitch
  %               (ly:make-pitch 0 0 0))))

The NoteEvent object is the first object of the 'elements property of
someNote. (The `display-scheme-music' function is the function used by
\displayMusic to display the scheme representation of a music
expression)

  #(display-scheme-music (first (ly:music-property someNote 'elements)))

  % ==> (make-music
  %       'NoteEvent
  %       'duration
  %       (ly:make-duration 2 0 1 1)
  %       'pitch
  %       (ly:make-pitch 0 0 0))

Then, the note pitch is accessed thourgh the 'pitch property of the
NoteEvent object:

  #(display-scheme-music 
     (ly:music-property (first (ly:music-property someNote 'elements))
                        'pitch))
  % ==> (ly:make-pitch 0 0 0)

The note pitch can be changed, by setting this 'pitch property:

  #(set! (ly:music-property (first (ly:music-property someNote 'elements))
                            'pitch)
         (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
  \displayLilyMusic \someNote
  % ==> d'

11.3.3 Adding articulation to notes (example)

I don't know where you got this example from, but there are mistakes.

  `cons' is used to add an element to a list

The wording is poor: cons does not modify the existing list. Maybe that
should be precised, for instance: (without modifying the original list).

11.4.1 Markup construction in Scheme

  "One can not feed the #:line, #:center, or #:column) commands with a
  variable or the result of a function call."

This sentence should more general, we're talking here about commands
accepting markup-list arguments, eg. #:line, #:center-align or #:column
(but there are others, like #:fill-line).

nicolas