Re: Doc: Reorganize music functions material. (issue970044)

[markpolesky]

Reviewers: carl.d.sorensen_gmail.com, Neil Puttock,


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.

Description:
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.

Please review this at http://codereview.appspot.com/970044/show

Affected files:
  M Documentation/extending/programming-interface.itely
  M Documentation/notation/changing-defaults.itely
  M Documentation/notation/notation-appendices.itely
  M scm/c++.scm
  A scm/document-type-predicates.scm
  M scm/documentation-generate.scm