[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Another documentation issue

From: Stephen
Subject: Re: Another documentation issue
Date: Thu, 19 May 2005 09:48:35 -0500


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


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

- Graham

lilypond-devel mailing list

reply via email to

[Prev in Thread] Current Thread [Next in Thread]