Doc: Reorganize music functions material.

Doc: Reorganize music functions material.

* Remove nodes from Extending that are covered in
  Notation:
    2.1.1 Music function syntax
    2.1.2 Simple substitution functions

* In Extending 2.1, move `Void functions' to end
  of section, so `Functions without arguments'
  comes first.

* Use a consistent indentation format for music
  functions.

* Make some minor formatting/wording changes.

* Create type-predicates-doc-string to document
  type-p-name-alist automatically.

* Add notation appendix
  `Music function type predicates' to include
  type-predicates-doc-string.

[Carl, 2010-04-26 14:37:56]

Looks mostly good to me.


Thanks for doing this,

Carl

http://codereview.appspot.com/970044/diff/1/2
File Documentation/extending/programming-interface.itely (left):

http://codereview.appspot.com/970044/diff/1/2#oldcode38
Documentation/extending/programming-interface.itely:38: * Music function
syntax::
I am not in favor of eliminating Music function syntax in Extending.  This
should be a complete discussion of Music function syntax, which is more general
than the syntax for simple substitution functions.

http://codereview.appspot.com/970044/diff/1/2
File Documentation/extending/programming-interface.itely (right):

http://codereview.appspot.com/970044/diff/1/2#newcode61
Documentation/extending/programming-interface.itely:61: #(define-music-function
This new indentation is interesting.  It's consistent with Scheme indentation
rules, which is probably a good thing.  But I'm still not sure if I like it.

I guess on balance I agree with it.

http://codereview.appspot.com/970044/diff/1/3
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/970044/diff/1/3#newcode3628
Documentation/notation/changing-defaults.itely:3628: @example
I think that making this a table is better than just listing it.

Also, for simple substitution functions, we are using only variables that will
be directly substituted in a lilypond music expression, so I think we should
just mention ly:music?, markup?, number?, string?, and symbol?.  boolean?,
list?, and pair? aren't generally used in simple substitution functions.

But I don't feel strongly about this.

http://codereview.appspot.com/970044/diff/1/3#newcode3647
Documentation/notation/changing-defaults.itely:3647: confusing at first. ...
As I mentioned in my previous email, I think the right thing is to just say that
Scheme expressions inside a #{ #} block should be identified with $.

[Neil Puttock, 2010-04-28 21:42:05]

http://codereview.appspot.com/970044/diff/1/3
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/970044/diff/1/3#newcode3641
Documentation/notation/changing-defaults.itely:3641: @ref{Music function type
predicates}.
There's a danger here that users might think these are the only type predicates
allowed.

The list's only complete in so far as type-p-name-alist documents predicates
used internally for music functions and properties.

http://codereview.appspot.com/970044/diff/1/6
File scm/document-type-predicates.scm (right):

http://codereview.appspot.com/970044/diff/1/6#newcode20
scm/document-type-predicates.scm:20: "@item @code{"
indent

http://codereview.appspot.com/970044/diff/1/6#newcode32
scm/document-type-predicates.scm:32: "@multitable @columnfractions .33 .66\n"
indent

[Mark Polesky, 2010-04-29 07:13:18]

http://codereview.appspot.com/970044/diff/1/2
File Documentation/extending/programming-interface.itely (left):

http://codereview.appspot.com/970044/diff/1/2#oldcode38
Documentation/extending/programming-interface.itely:38: * Music function
syntax::
On 2010/04/26 14:37:56, Carl wrote:
> I am not in favor of eliminating Music function syntax in
> Extending.  This should be a complete discussion of Music
> function syntax, which is more general than the syntax for
> simple substitution functions.

Okay.  That makes me want to put "Simple substitution
functions" back, but if I do that, is it better to copy the
analagous node verbatim from the NR or to have the whole
node be a stub linking to the NR?

http://codereview.appspot.com/970044/diff/1/3
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/970044/diff/1/3#newcode3641
Documentation/notation/changing-defaults.itely:3641: @ref{Music function type
predicates}.
On 2010/04/28 21:42:05, Neil Puttock wrote:
> There's a danger here that users might think these are
> the only type predicates allowed.
> 
> The list's only complete in so far as type-p-name-alist
> documents predicates used internally for music functions
> and properties.

There aren't that many other predicates out there (see
http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00713.html).
And I'm happy to add the remaining ones to the alist if
that will justify using the word "complete".  (:

You also proposed a clever way to prevent labeling failed
type checks as "unknown" in the error message, which I'll
definitely add to the next patch set
(http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00725.html).

I'd like to do both.

[Carl, 2010-04-29 14:43:51]

I like the new suggestions.  Just a couple of comments.

http://codereview.appspot.com/970044/diff/1/2
File Documentation/extending/programming-interface.itely (left):

http://codereview.appspot.com/970044/diff/1/2#oldcode38
Documentation/extending/programming-interface.itely:38: * Music function
syntax::
On 2010/04/29 07:13:18, Mark Polesky wrote:
> Okay.  That makes me want to put "Simple substitution
> functions" back, but if I do that, is it better to copy the
> analagous node verbatim from the NR or to have the whole
> node be a stub linking to the NR?

I think a stub linking to the NR is correct.  Something like

Simple substitution functions are music functions whose output music expression
is written in LilyPond format and contains function arguments in the output
expression.  They are described in @ruser{Simple substitution functions}.

http://codereview.appspot.com/970044/diff/1/3
File Documentation/notation/changing-defaults.itely (right):

http://codereview.appspot.com/970044/diff/1/3#newcode3641
Documentation/notation/changing-defaults.itely:3641: @ref{Music function type
predicates}.
On 2010/04/29 07:13:18, Mark Polesky wrote:
> On 2010/04/28 21:42:05, Neil Puttock wrote:
> > There's a danger here that users might think these are
> > the only type predicates allowed.
> > 
> > The list's only complete in so far as type-p-name-alist
> > documents predicates used internally for music functions
> > and properties.
> 
> There aren't that many other predicates out there (see
> http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00713.html).
> And I'm happy to add the remaining ones to the alist if
> that will justify using the word "complete".  (:
> 
> You also proposed a clever way to prevent labeling failed
> type checks as "unknown" in the error message, which I'll
> definitely add to the next patch set
> (http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00725.html).
> 
> I'd like to do both.

Users can also write their own type predicates if they want to.  So perhaps we
should mention "predefined type predicates"

[Neil Puttock, 2010-04-29 22:13:49]

On 2010/04/29 07:13:18, Mark Polesky wrote:

> There aren't that many other predicates out there (see
> http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00713.html).
> And I'm happy to add the remaining ones to the alist if
> that will justify using the word "complete".  (:

As Carl's pointed out, it'll never be complete.

> 
> You also proposed a clever way to prevent labeling failed
> type checks as "unknown" in the error message, which I'll
> definitely add to the next patch set
> (http://lists.gnu.org/archive/html/lilypond-devel/2009-08/msg00725.html).
> 
> I'd like to do both.

OK, though I hope you won't add this, since it's nonsense:

        ;(,ly:item iterator? . "item iterator")

[markpolesky_yahoo.com, 2010-05-06 07:28:39]

New patch set uploaded.
http://codereview.appspot.com/1031044

Okay to push?
- Mark


      

[markpolesky_yahoo.com, 2010-05-06 07:28:41]

New patch set uploaded.
http://codereview.appspot.com/1031044

Okay to push?
- Mark