Re: NR5 and 6 feedback

[Carl D. Sorensen]

OK, NR 6 is mine.

It won't happen very fast, but I'll work on it as I can.

Carl


On 11/5/08 12:14 PM, "Trevor Daniels" <address@hidden> wrote:

> 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
>