Re: Doc updates from NEWS

[Han-Wen Nienhuys]

Graham Percival schreef:
> Everybody else, do any of the below items need to be in the docs?  If 
> so, please write something for them, because I don't understand them.  
> This is the last call; if nobody writes something for these soon, we'll 
> remove them from the TODO list.  (Actually, even if somebody _does_ 
> write docs for them, they'll still be removed from the list.  :)


> # Generic music functions may now also be used on articulations and 
> chord elements


you can write a music function and do

  <c-\myMusicFunction -. >

this will run myMusicFunction on the ArticulationEvent for -.

> # Calculation of extent and offset of grob is now controlled via the 
> X-extent, Y-extent, X-offset and Y-offset properties, [I suspect this is 
> documented, but I don't really understand it enough to tell for sure.]
> #
>
> # Each grob property can be a procedure. If this is the case, it is 
> assumed to be a routine that calculates said property. This is a major 
> internal cleanup, which also provides advanced tweakability for power 
> users. [I don't even know what this means...!]
>
> # Each grob property may also be a "grob closure." This means that it is
> possible to combine functions.
> #

Properties (like thickness, direction, etc.) can be set at fixed values 
with \override. That's nothing new, eg.

  \override Stem #'thickness = #2.0

new things is: you can put in a Scheme procedure now,

  \override Stem #'thickness = #(lambda (grob)
    (if (= UP (ly:grob-property grob 'direction))
        2.0
        5.0))

this will trigger the specified procedure during the formatting. In this 
case, it will set the thickness to 2 (upstem) or 5 (downstem) depending 
on the stem direction.

You can also combine rules like that with "grob closure". Here is a 
setting from AccidentalSuggestion,

        (X-offset . ,(ly:make-simple-closure
                      `(,+
                        ,(ly:make-simple-closure (list 
ly:self-alignment-interface::centered-on-x-parent))
                        ,(ly:make-simple-closure (list 
ly:self-alignment-interface::x-aligned-on-self)))))


it centers the grob on its X-parent, and on itself. Both results are 
added (the + operator). This is probably too advanced for the manual though.

Here you can see another aspect: the size and dimension of a grob is 
also computed through properties. The older mechanism was more 
convoluted, and wasn't documented.

--

Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen

LilyPond Software Design
 -- Code for Music Notation
http://www.lilypond-design.com