Re: lilypond-user Digest, Vol 149, Issue 159

[Flaming Hakama by Elaine]

 

From: Kieren MacMillan <address@hidden>
Subject: Re: lilypond-user Digest, Vol 149, Issue 155

> it makes me feel frustrated as a professional programmer that after years of using lilypond, I still have very little clue how it works

I?ve heard you say that a lot, and it confuses me. As an erstwhile professional programmer (thankfully just about to take down my shingle for a long sabbatical of composition, and hopefully forever!), *how* Lilypond works has been clear to me almost from my first day working with it. Now *making* it do what I want (e.g., coding in Scheme or C++) is a different story?

Since I understand programming languages rather well, if I understanding how something is organized, then I can code it 100% of the time. 

Surely, I will have to refer to manuals to find out specifics about objects, functional prototypes, etc.

But the transition from concept to execution is simply a matter of following the recipe.

Within the lilypond universe, however, this is complicated due to the several languages used (scheme, guile scheme and lilypond-specific syntax).

So, it is often not enough to know what you want to do, you need to know in which realm this activity is conducted.

It doesn't help that many things are implicit and based on contexts which are invisible and undocumented--or you can't find the documentation, which in the heat of the moment is more or less the same thing.

Also, the tendency of schemers to endlessly repeat the mantra "everything is a list" without really acknowledging that is both inaccurate and unhelpful.

(Yes, everything may be a list.  But depending on what you need to *do* with that list, there are undocumented requirements like, the first element needs to be a function, the second and third elements need to be strings, the fourth needs to be an ly:music type, the fifth element needs to be a list of notes.)

 

> they would be a simple, high-level introduction about how all the pieces and parts are put together, so you could say, "ok, here's where the stuff I'm doing fits in, so here is the type of info that I will need to learn?.

There are both scope and chicken/egg problems with that idea (or, at least, what I *infer* is your idea). For example, let?s say you want to teach a newbie how to write a simple song with piano accompaniment.

1. Do you teach them \relative mode (which is confusing to many newbies, and ultimately not a best practice anyway)?

2. Do you break out the dynamics into a separate context (which for more complex pieces is probably a best practice)? If so, you need to introduce the concept of contexts, and possibly customize them.

3. Do you separate the global items into their own variable (a best practice for all but the simplest examples)?

etc. etc. etc.

Yes, this is exactly what would be helpful!
Something that outlines from beginning to end how to do implement something "the right way", one step at a time.

Users can decide for themselves how much complexity to take on, based on their needs, and stop at the point where they are comfortable.

Then, to make it killer, provide template code for exactly that exact level of complexity that they want to bite off.

 

  > Yes, I agree that this is the best starting point for documentation: Finding out what users need to know.

When I Google "lilypond add slur?, the third hit is <http://www.lilypond.org/doc/v2.18/Documentation/learning/ties-and-slurs>, which shows exactly how to add a slur. Is that not direct enough for newbies, such that we have to spend valuable (nigh non-existent) resources on making more documentation, links, and navigation/search tools?

Not sure how this is relevant.  How does the result for this query help uncover what it is that users need to know?

I guess you are pointing out that, from the suggested list of questions, some of them are trivially found in the docs.

But this does not address either the organization, which is to say, the TOC or index or FAQ organized by what users want to do.

And what about all the inevitable cases where it is difficult to find the information, or requires looking at several disjunct places in the docs.?
We can't know what are the gaps in documentation until we generate assess what people need to know (regardless of how easy it is, or how easy it is to locate).

 

 > A complimentary approach would be to tag the sections of documentation according to various topics.

That at least sounds like a good approach, from a cost/benefit perspective.

> Especially including the things, like "instrument", for which there are no lilypond objects at all.

?No objects? meaning what exactly?

Kieren.

Without getting too technical, objects are things that you can create, have properties and relationships with other well-defined objects.

This is true for things like staves, staff groups, scores, books, etc.
You can say:  \new Staff = { ... } to create a new staff because there is an object class called Staff that is well-defined.

It has known properties like Staff.TimeSignature, Staff.extraNatural, etc.

Other objects (Staff Groups, Books, etc.) know how to handle this Staff object, or several Staff objects.

However, in the case of "instrument", there is no such object so you cannot create one.

There are certainly properties of other objects (namely, staves) that have "instrument" in the name, like Staff.instrumentName, Staff.shortInstrumentName, Staff,midiInstrument.
However, these are *properties of a Staff object*.
There is no way to create an "instrument" outside the context of a staff, or identify or change its properties.
You cannot add an instrument to a staff or any other object.

If there were, the syntax might be more like:

violin = \new Instrument {
    Instrument.name = 'violin'
    Instrument.shortName = 'v.'
    Instrument.midi = 'violin'

    Instrument.clef = treble
    ...

}

\new Staff {

    Staff.Instrument = \violin

    \violinMusic

}

As an aside, an outstanding problem with lilypond is that it is difficult to write multi-instrument parts.
This points to a lack of clarity of design around the distinction between a voice, instrument and staff.

At its core is the lack of a coherent concept of instrument.

Which is to say, while you might point to the Staff as the place where most instrument information is situated, Staff and Instrument are clearly not identical concepts, nor is Instrument a proper subset of a Staff.

Perhaps the reason there is no such Instrument object in lilypond is that an "instrument" is not a grob. 
There is no place that an "instrument" appears on the page, except as a label for a staff.

Yet, for the purpose of this discussion, it is clear that everyone thinks in terms of "instruments".

So, the documentation ought to explain exactly how this commonsense conceptual notion of "instrument" maps to the actual objects and properties that are available.

 

David Elaine Alt

415 . 341 .4954                                           "Confusion is highly underrated"

address@hidden

self-immolation.info
skype: flaming_hakama
Producer ~ Composer ~ Instrumentalist
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-