I propose either
1) only putting the layout object as a link to the program reference so the user can link to the engraver from the object page in the program reference and then link to the event from the engraver page or
2) list the object first, then the engraver and then the event last under the Program reference link on each page in the documentation.
Listing the information in the same format and order from page to page would make it easier for a newbie to learn to navigate to the information he needs sooner. The Program Reference is noticeably more consistent in the way the information is layed out than in the documentation in the 'See also' sections.
I personally have not figured out how to use the event yet, object yes, engraver yes, event no.
Stephen
----- Original Message ----- From: "Han-Wen Nienhuys" <[EMAIL PROTECTED]>
To: "Graham Percival" <[EMAIL PROTECTED]>
Cc: "lily-devel" <[email protected]>
Sent: Friday, May 13, 2005 6:44 AM
Subject: Re: Another documentation issue
Graham Percival wrote:
On 12-May-05, at 2:40 AM, Han-Wen Nienhuys wrote:
Graham Percival wrote:
Maybe one alternative is to skip the links to the music expressions (*Event) all together since they can be found by navigating Arpeggio -> Arpeggio_engraver -> arpeggio-event. This would also reduce the number of links that have to be kept up to date manually in the manual.
I favor this solution. Is this ok?
I guess the Event types can be ditched if somewhere it is explained clearly that you can do
\displayMusic ...
and see what's inside.
What's this? How is \displayMusic supposed to work?
try
\displayMusic { c4-\arpeggio }
The main proposal here is that instead of having this:
Arpeggios blah blah @seealso _ArpeggioEvent_, _Arpeggio_
we just have this:
Arpeggios blah blah @seealso _Arpgeggio_
If a user wants to see the internals stuff, he clicks on _Arpeggio_. The very first line tells
him that Arpeggio objects are created by Arpeggio_engraver and Span_arpeggio_engraver;
following those links will get him to arpeggio-event. We don't need a link to
arpeggio-event in the refman page about Arpeggios.
My worry is that encouraging people to find out thngs on their own in the program-reference on their own might also not be productive. If you think many links is confusing, than it would be best not to have them browse the internals page (with its many links.)
-- Han-Wen Nienhuys - [EMAIL PROTECTED] - http://www.xs4all.nl/~hanwen
_______________________________________________
lilypond-devel mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
_______________________________________________ lilypond-devel mailing list [email protected] http://lists.gnu.org/mailman/listinfo/lilypond-devel
