Re: Reorganization of Docs

[Trevor Daniels]

OK Carl, you've convinced me.  Well, sort of.  It was
the realisation that \displayLilyMusic would be very
useful for checking the output of a Scheme function
which created music while it was being developed that
really convinced me.  It should be in NR 6,

Trevor

----- Original Message ----- 
From: "Carl D. Sorensen" <address@hidden>
To: "Trevor Daniels" <address@hidden>; "Graham Percival" 
<address@hidden>
Cc: "lily-devel" <address@hidden>
Sent: Friday, January 02, 2009 1:41 PM
Subject: Re: Reorganization of Docs





Trevor wrote:

> I agree with Graham.  \displayLilyMusic has nothing to
> do with the internal representation of music.  It simply
> shows the effect of \transpose.

Graham wrote:

> Transposing.  Also, translating from relative to absolute.  Hey, I
> never claimed that it was *vitally useful* useful.  :)

This particular example shows the effect of transpose, but to me it is a
somewhat contrived example.  The way most people see the effect of transpose
is in its effect on notes.

displayLilyMusic is not used to achieve music output; it's used to
understand what's going on inside of LilyPond.  You can't take its output
and pass it to a parser; the output of displayLilyMusic goes to the console,
not to some other variable.

Do you really think that somebody is going to translate from relative to
absolute by entering their music in relative mode, then using
displayLilyMusic to put the output to the console or a log file, and finally
paste that music expression into a LilyPond input file?  And then, if they
make changes to the original file, repeat the process again manually?  If
they're going to do that more than once, they NEED to write some code that
will do it *in the file*.  The implied process here is like using an SVG
editor to move an accidental, instead of adding some extraOffset.

Trevor wrote:
> Are you thinking of \displayMusic maybe, which is already in
> NR 6?

Graham wrote:
> I must admit that NR 3 is pretty much an "odds and ends"
> section.


displayMusic is a means to display the Scheme representation of the music.

displayLilyMusic is a means to display the input file representation of the
music.

In my mind, displayMusic and displayLilyMusic are parallel functions, both
aimed at showing the interested user what's happening with a particular
music expression as it's parsed and operated on by the magical internals of
LilyPond.  Neither has as its goal the production of notes on paper (or in
midi files).  Since they're parallel functions, they belong together.  And
there's nothing equivalent tying displayMusic to the contents of section
3.3.

Graham wrote:
> But the best argument I can give is that it doesn't
> require scheme, so it shouldn't be exclusively in NR 6.

I agree that it doesn't require scheme.  But its use is really aimed at
somebody who wants to extend LilyPond somehow.

Some of the simple music functions that are shown in NR 6 barely require
Scheme.  The Scheme is just a wrapper, and it's really LilyPond syntax in
the file, other than the Scheme that is already given in the example.

Perhaps you should know that I am also proposing a name change to NR 6, from
"Interfaces for programming" to "Extending LilyPond".

This discussion has strengthened my belief that displayLilyMusic belongs
primarily in NR 6.   If there needs to be a link in LM 3.3, then I'm not
opposed to it.  But as I look at LM 3.3, section 3.3.4 is clearly an
outlier.

Carl