Re: commands list and syntax

[Graham Percival]

hernan gonzalez wrote:
> For one (for the first) thing: The "Commands index"
> http://lilypond.org/doc/v2.10/Documentation/user/lilypond/LilyPond-command-index 
>
> is supposed to be "an index of all LilyPond \commands".
> Now, that list (besides being non-categorized, with the "important"
> commands buried among lots of gregorian-stuff and such)

We can't do anything about that; texinfo creates an alphabetical index.

> does not
> include a lot of very basic commands (\score \midi  \markup
> \appoggiatura \version ! ) .
> Or am I missing something and those are not "commands" ?

The general idea is that these are for things like \markup and 
\appoggiatura (ie stuff that goes inside the music definition), but I 
wouldn't object to including things like \version and \score in that index.

Please see:
http://lilypond.org/web/devel/participating/documentation-adding


> In some example in the docs, it is stated:
> http://lilypond.org/doc/v2.10/Documentation/user/lilypond/Saving-typing-with-identifiers-and-functions 
>
>
> ... we've seen static substitution – when LilyPond sees \padText, it
> replaces it with the stuff that we've defined it to be (ie the stuff
> to the right of padtext=).
>
> (actually that "at the right" seems misleading to me ; it's actually
> the "block" or "atom" following the = sing. I think that that concept
> should be more explained in the docs. If I understand weel, the braces
> are used not just to enclose "expressions" or "fragments of music")

Err... concepts like "block" and "atom" might be familiar to you (as a 
programmer), but they're not familiar to me!  The simplest way I could 
think of writing that part was to talk about "the stuff to the right of..."

I'm certainly not opposed to rewriting it, though!  Again, see

http://lilypond.org/web/devel/participating/documentation-adding

and please send an exact proposal.


> That phrase  led me to think that we have in general a textual macro,
> something like  a #define in C. But if i write
>
> myitalic = \italic
> a^\markup{ \myitalic hi}

That's because there's no main music expression; you need {} around the 
second line.

> it does not compile, in spite of this being valid:
>
> a^\markup{ \italic hi}

This does?  ... well, it kind-of works.  In version 2.11.27, I get an 
error message, and only the "hi" is printed.


> That command index, besides, links to the relevant page of the
> documentation. It would be nice to have somewhere some kind of
> reference of all the commands with their syntax (arguments;  and
> context, if relevant).

Something similar to  Appendix E Cheat sheet, but for more advanced 
commands?  That would certainly be useful; again, see the "how to help 
with the documentation" page.

Cheers,
- Graham