Re: Example massacre

[Mats Bengtsson]

I think we have to realize that there is no single form of
documentation that suites all needs. We already now have
the Tutorial which contains material from the Notatation
manual but presented in another way. The set of examples in the
Tips and Tricks and in the Regression Tests documents is another
way of presenting more or less the same material in a form that
often is very useful.
One advantage of these collections of examples, as pointed out below,
is that it's very easy to browse through. When answering questions
on the mailing lists, I have to admit that I very often find the
answer either that way or by running 'grep' on input/*/*.

Of course, viewing these examples as a part of the documentation,
means additional support work. One possible way out would be to
actually integrate all the useful examples into the main manual,
but also collect all "interesting" examples from the manual into
a "Collection of Examples" document, which has links back to the
corresponding section in the notation manual.

Regarding Bret's proposal for a single huge contrived example showing
lots of strange feature, I don't think it's that useful, since the
code of that example will be completely incomprehensible, for those
who want to see how a particular combination of features is done, for
example, even if each separate feature has an example in the manual.

   /Mats

Luise Marion Frenkel wrote:
> I am an sporadic Lilypond user, who tries to keep up to date with the 
> syntax changes reading the user and devel lists. I have to type many 
> different sorts of music, and usually no template fits me well. I find 
> it very difficult to find the answers for my questions in the manual. 
> When the Tips and Tricks were more complete, I just had to roll that 
> page down until I found what I needed. Most tricks I needed were 
> perfectly documented there, and I easily recognized what I needed by 
> the pictures. Now I have to try to remember what picture (that is 
> lilypond image) that once I saw in the manual is what I need and where 
> it could be and start browsing the One-Page manual. Google searching is 
> not practical for those who are not native-english speeker because 
> often they do not know what the right term is. Images have a 
> universal meenig and spare us of looking the glossary. And for those who 
> do not do "standard" scores, but weird arrangements which are fitting 
> for their practice, it is not always necessary to use the RIGHT thing, 
> but something which does the job.
>
> I am still looking at the Tips and Tricks of former Lilypond branches, 
> which are more complete, and updating the code. I do not think that the 
> Tips & Tricks should be a compillation of all lilypond snipets or 
> examples in the manual for that would again be to much. I just liked 
> very much the old Tips and Tricks.
>
> I think that even advanced Lilypond users need to look into the manual 
> as soon as they do something different. The tutorial must focus on 
> novice users, but the manual has to be also fit for the frequent users.
>
> Since this thread started together with the figured-bass issue, is there 
> by the way any difference between #3 and 3#. A Ricordi Score for the 
> Vivaldi Gloria RV589 uses both, but more #3. I coul not find a way to 
> typeset this. I do not know anything about figured bass, except that the 
> organist with whom I shall play knows how to handle them!
>
> TIA
>
> Luise
>
>
> On Wed, 1 Dec 2004, Han-Wen Nienhuys wrote:
>
>
> > Of course, if you know what you're looking for -like Mats, I suppose-
> > then the tips & tricks collection is an easy document. However, I
> > think we need to focus on novice users which are not sure what they
> > are looking for exactly. Also, doesn't a broken up document (like the
> > manual) work better with Google searching?
>
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-devel

--
=============================================
        Mats Bengtsson
        Signal Processing
        Signals, Sensors and Systems
        Royal Institute of Technology
        SE-100 44  STOCKHOLM
        Sweden
        Phone: (+46) 8 790 8463                         
        Fax:   (+46) 8 790 7260
        Email: address@hidden
        WWW: http://www.s3.kth.se/~mabe
=============================================