problems with learning lilypond

[John Sellers]

I am in Silicon Valley.  I've never met and talked to another lilypond 
user face to face.  It is lonely out here.

I've used lilypond off and on for a few years AND HAVE NEVER BEEN ABLE 
TO REALLY LEARN IT WELL!

There are five reasons

1) lack of context
2) lack of context
3) lack of context
4) lack of context
5) lack of context
6) NOTHING HAS MEANING WITHOUT CONTEXT --- EVER!

I'm very tired of having a few hours to do something different, going to 
lilypond documentation and getting something like

"use such and such to do so and so".

fine so far. but how in God's Green Earth am I going to use something like:

\paper {    }

If I don't know what context it works and what context it does not 
work?  If like an idiot I go into my LY file and insert paper and put my 
between-system-space or anything ELSE on the same page with a lot of 
other variables which control things.  Why don't they ALL work WHENEVER 
I try to use them...the answer is of course LACK OF CONTEXT.  For 
correct context, I have to put the \paper {}  in the right part of the 
program.  I have to tie the variables to whatever they are going to 
effect.  Or do I?  I haven't a clue.  Why.....here we go again....LACK 
OF CONTEXT.

Here is one way you can solve this problem.

NEVER DOCUMENT ANYTHING OUT OF CONTEXT except with a link that LEADS TO 
THE CORRECT CONTEXT.

YOU HAVE TO BE SYSTEMATIC!  Consider the following:

Every feature must be documented....right? So are we talking about a 
desert of documented sand pebbles in a jar or are there relationships 
between them?  WOW!  there are DEPENDENCIES --- A dependences are B 
depends on C --- oops, C depends on A ----NOT GOOD.

So what is one to do?  Well, you could use a topological sort of all 
capability dependencies using generality as the sort discriminant.  Find 
all the cycles and BREAK THEM.  Organize things in this way so now you 
have a structure which has an entry point for the user for every 
feature.  Look, dependency is just another way of say CONTEXT.  If 
context goes in a circle then you end up defining  A grumpet B  and then 
defining B as anti-grumpet A, which is has no more meaning than being a 
tautology. 

In the best of all worlds, a user coming to the documentation WITH NO 
KNOWLEDGE OF LILYOND in wanting to do something like control vertical 
spacing, and if you linked back to more and more general contexts with 
clear examples and explanations in a systematic way, then at some point 
you would reach the context that includes the user's context, and there 
the user can make the connection of how to find the way to apply 
vertical spacing to his/her specific situation.

Here is a hint.  You run lilypond executable and makes those 
connections, so the relationships already exist and are documented in an 
executable form.  Here is another hint.  The nature of MEANING is the 
one to one correspondence between two different systems.  So we have a 
system to compile which we know to be complete, and we want a system to 
provide meaning to the user...could it be that we could parse the code 
to provide CONTEXT to the user?  yes, yes, yes, yes, yes, YES---Each 
individual thing has meaning if we have CONTEXT of each thing.  Each and 
every thing we wish to document is carried out and executed by the compiler.

As for additional documentation, such as you already have in abundance.  
If you had a truly complete general to specific dependency tree of all 
features, there you could ALWAYS link every reference to its proper 
place in the dependency tree.  This would mean that someone reading your 
GDP would ALWAYS have a path back to context of the currently examined 
feature.

Now one really slick way to do this would be hyperlink ALL compilable 
code in the documentation, automatically generated through a link 
compiler that would establish a link to point to the right place in your 
dependency tree (e.g. right context) for learning about the particular 
feature.  This linked structure is nothing more than a remediation tool 
which all users, new and experienced could use to quickly brush up on 
how to use any feature in lilypond.  There IS a way to do this.  
Really!  So why not?   I guarantee that when all is said and done, it is 
a shorter path for the user AND to YOU to provide good communication 
than what you are doing now....because once done, it can be maintained 
in parallel with development since it reflects the structure of 
compiling and therefore development.

---end of tirade--