Re: Another documentation issue

[Stephen]

Graham,

That was my thought exactly, except instead of saying 'get rid of' I would 
have said 'replace'.

For instance, in 5.7.4 Metronome marks, 'See also' points to 
MetronomeChangeEvent. Why not replace that with MetronomeMark? In the 
MetronomeChangeEvent page, I click on Metronome_mark_engraver and from there 
MetronomeMark. It is nice that the program reference is so well 
cross-referenced, but as a new user who is studying the documentation, I 
spend some time trying to understand why I was sent to the event page first 
and how I can use the information on that page to write my lilypond files.

The person putting the documentation together is a teacher. And the teacher 
is implying to the newbie that he should learn how to use 
MetronomeChangeEvent before he learns how to use MetronomeMark. Well, not 
you personally, but the documentation is how we learn to use Lilypond. I 
still do not understand how to use the information o the 
MetronomeChangeEvent page or any event page to write Lilypond files better.

As long as I am getting a little philosophical, I want to bring to the 
developers attention something that concerns me. In 1.4 Music representation 
there is the following quote:

> We write a program capable of producing sheet music, and adjust the format 
> to be as lean as possible. When the format can no longer be trimmed down, 
> by definition we are left with content itself. Our program serves as a 
> formal definition of a music document.>

I wonder if all the developers are still on board with the goal of keeping 
the format 'as lean as possible'?

Another interesting quote (from 1.5 Example applications):

> We have written LilyPond as an experiment of how to condense the art of 
> music engraving into a computer program. Thanks to all that hard work, the 
> program can now be used to perform useful tasks.>

This is writtien almost as if performing a useful task is of secondary 
importance to condensing the art of music engraving. I am sure this is 
written this way in order to maintain a sense of humility and it is well 
written, but still we have 'condensed' and 'lean' as words defining the 
purpose and goal of writing Lilypond and for Lilypond. My take on it is 
anyone who joins these two in developing Lilypond, should first adopt their 
philosophy.

And finally, another important quote (from 1.2 Automated engraging) that 
defines a goal I am not sure all the developers are on board with:

> Over the course of years, the software can be refined to do more and more 
> automatically, so manual overrides are less and less necessary.>

Stephen

----- Original Message ----- 
From: "Graham Percival" <address@hidden>
To: "Han-Wen Nienhuys" <address@hidden>
Cc: "lily-devel" <address@hidden>
Sent: Wednesday, May 18, 2005 7:54 AM
Subject: Re: Another documentation issue


> On 13-May-05, at 4:44 AM, Han-Wen Nienhuys wrote:
>
> > Graham Percival wrote:
> > > 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.)
>
> They don't need to "find" things on their own.  The very first link on a 
> grob page is a link
> to grobEvent.
>
> We want a link from the user manual to a useful part of the program 
> reference.  But
> grobEvent isn't very useful.  Most of the time that somebody wants to look 
> at the
> program reference, they want to see the grob's properties.  If they need 
> to find out
> what property the grob belongs to, they can click the grobEvent link from 
> the
> internals page about grob.
>
> Having a link to grobEvent in the user manual isn't very useful, so IMO I 
> should
> get rid of them.
>
> Cheers,
> - Graham
>
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel