Re: Another documentation issue

[Stephen]

I think the sheer number of links is not confusing, but the fact that the 
information is not given in a consistent order from page to page is 
confusing.

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" <address@hidden>
To: "Graham Percival" <address@hidden>
Cc: "lily-devel" <address@hidden>
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 - address@hidden - http://www.xs4all.nl/~hanwen
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel