Re: NR5 and 6 feedback

[Trevor Daniels]

Carl

I'm partly through editing NR 5 but I broke off to try to complete NR 1.2 
and other sections in NR 1 and NR 2, which I see as needing to be finished 
before 2.12.  No one has yet touched NR 6, apart from perhaps dumping things 
in here from elsewhere.  It would be really great if you could adopt NR 6 
and bring it to the standard of the rest of the docs.  Then, if I haven't 
got back to NR 5 by then I'd be happy for you to add to that too, but it's 
really NR 6 that needs attention right now.  You'd be ideal to do that.

I seem to remember suggesting adding center-visible some time ago, but then 
it slipped away.  It surely should be added for neatness, even though it's 
hard to think of a use for it.  I'd support your doing this.

Trevor


----- Original Message ----- 
From: "Carl D. Sorensen" <address@hidden>
To: "lily-devel" <address@hidden>
Sent: Wednesday, November 05, 2008 1:44 PM
Subject: NR5 and 6 feedback


I don't know who's been editing NR5, but it's really nice!  I was using it
to make some tweaks, and I really appreciate the improved quality it has
since a couple of years ago.

I really think that LilyPond's documentation is pretty close to excellent
now.  I can find what I need and figure out how to do things.  Thanks to all
who have worked on it, especially Graham for setting out the policies that
make the docs really useful.

I have some suggestions for whomever is doing NR5 and 6.  If nobody is, I'll
be happy to make the changes myself, but I don't want to step on somebody
else's toes.

In the section on break-visibility in NR 5.4.6,  7 of the 8 possible values
for the break-visibility property are shown, along with a statement that
center-visible (the value of which is never defined, and must be inferred by
the reader) is not predefined.

It seems to me that we ought to go ahead and define center-visible in
scm/output-lib.scm and add it to the table.  It would make that section
easier to read and more complete.


Second issue:   In NR 6.1.1, Overview of music functions,  the list of
argument types includes pair? which is ascribed to "A pair of variables".  I
think it would be better to say "A Scheme pair, which includes lists."  The
pair? check is preferred to the list? check because it's faster.

Also, in NR 6.1.1, I get a bit of a misunderstanding.  6.1.1 is supposed to
be an overview of all music functions, but it says:

---  Beginning of quote

Making a function which substitutes a variable into LilyPond code is easy.
The general form of these functions is

function =
#(define-music-function (parser location var1 var2...vari... )
                       (var1-type? var2-type?...vari-type?...)
 #{
   ...music...
 #})
where

vari    ith variable
vari-type?    type of ith variable
...music...    normal LilyPond input, using variables as #$var1, etc.

---- End of quote

This is the general form only for "variable substitution" type functions,
because it mentions #{ ...#} which is only used when writing LilyPond
input-style music.  Lots of other music styles can be written instead.  In
fact, most of the functions I write just use Scheme music definitions.  I
think the "variable substitution type functions are described in NR6.1.2.,
so I think this definition should be moved to NR 6.1.2.

I think that NR 6.1.1. should contain something like the following:

Music functions can be defined to simplify repetitive tasks and to allow a
greater degree of control over LilyPond output.  Music functions will often
be used when a simple LilyPond variable definition cannot achieve the
desired result.

Music functions can be as simple as variable substitution expressions.
They can also use the full power of Scheme.  This section describes some
common uses for music functions and provides some examples as a guide for
creating music functions.

---- End of recommended text for NR 6.1.1.

I think the title of section 6.1.7. should be changed to "Predefined music
functions" instead of "Available music functions".  And I think the
introductory text:

"The following commands are music functions"

Should be changed to:

"The following commands are predefined music functions.  The definitions for
these functions are found in  ly/*-init.ly."


Thanks,

Carl



_______________________________________________
lilypond-devel mailing list
address@hidden
http://lists.gnu.org/mailman/listinfo/lilypond-devel