[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: NR5 and 6 feedback
From: |
Carl D. Sorensen |
Subject: |
Re: NR5 and 6 feedback |
Date: |
Wed, 5 Nov 2008 12:09:38 -0700 |
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
>