lilypond-user
[Top][All Lists]
Advanced

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

Re: problems with learning lilypond


From: Carl D. Sorensen
Subject: Re: problems with learning lilypond
Date: Wed, 19 Nov 2008 13:17:34 -0700



On 11/19/08 1:54 AM, "John Sellers" <address@hidden> wrote:

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

I think that those who have used lilypond off and on for a few years are
actually at a disadvantage, because they (including me until late last year)
never bothered to read the Learning Manual.

The Learning Manual is an excellent resource to give the context that was
missing in my previous attempts.

> 
> 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 {    }

Have you tried the 2.11 documentation?  I find it to be a dramatic
improvement over the 2.10 documentation.  You really should try it.  Since I
started using the 2.11 documentation I have been able to everything I have
tried to do.  (This wasn't the case previously).

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

This specific question (about where the \paper{} block goes) is now covered
nicely in the documentation.  See Notation Reference 3.1.3. File structure.
However **NOTE TO DOCUMENTATION TEAM** that section of the manual should
probably include both a \paper{} and a \midi{} in an example.
 
> 
> 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.

You would be doing a great service to LilyPond by identifying the cycles you
find in the documentation.  Even better, you could propose alternate wording
or alternate organization.  The best place to make such recommendations is
on the -devel list, rather than on the -user list.  I have personally found
the LilyPond development team to be very receptive to specific suggestions
for change and not very responsive to rants that just say "you're doing it
all wrong".  If you have a better idea, share it and it's likely to get
implemented.

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

A simple example of your proposal would greatly strengthen your argument,
because you would have to wrestle with the specifics of what you mean.  It's
easy to make broad generalizations, and much more difficult to make specific
suggestions for improvement.  Perhaps you could either make such an example,
or provide us with the path you tried in the 2.11 documentation only to be
stymied by the lack of context.

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

If you know how to provide this, you're very welcome to do so.  If you don't
then all you're doing is ranting.

And don't give us hints -- give us useful information.  If you want to get
something implemented, you shouldn't start by asking us to guess what you
mean by giving us hints.

One of the challenges with the LilyPond parser is that it is not
state-independent, which means that it's harder to document than a
state-independent parser.  I remember when I was first trying to learn
LilyPond that I generated an approximate BNF form grammar from LilyPond,
thinking it would help me learn to do what I needed to do.  Turns out, it
wasn't that helpful to me.


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

I don't know what you mean by the dependency tree.  If you'd like to try
generating a dependency tree (or even a partial dependency tree) then
perhaps I could understand what you're asking.

If I understand what you mean, the dependency tree is already part of the
documentation.  It exists in the internals reference.  Section 2.1 lists the
contexts.  Each context lists (and is linked to) the layout objects it
creates, the contexts that can be contained within it, and the engravers it
contains.  Each engraver lists the objects created, the music types
accepted,  and the properties the engraver reads (with links to each of the
engravers, music types, and objects).

There is also a list of engravers, with each engraver hyperlinked to the
various contexts that contain the engraver by default.

The challenge is that this isn't really a tree structure.  Engravers aren't
limited to a single context, and properties aren't limited to a single
layout object.  So the tree looks more like a net, and I think that the
"dependency tree" idea breaks down.  If you can show us how it should work,
that would be great.


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

Back at you.  If there is a way to do it, why not?  It's your itch to
scratch, so scratch it!  Or, as is sometimes said, "Patches gratefully
accepted."

I wanted transposable fret diagrams.  I could have come on -user and tried
to convince everybody that this was the next great feature that needed to be
added to LilyPond, and hoped that somebody would do it.  But if I did that,
I'd still be waiting.  Another user sponsored the development of the
FretBoards context, and then I modified the FretBoards context to provide
the functionality I wanted.  Now the feature I want is there, and I can
tweak it to perform exactly how I want it to.  Ahh, the benefit of
open-source software development!

Somebody else (Valentin?, or Francisco, perhaps?) wanted harp pedal
diagrams, and so they made a stab at the code.  Turns out that their code
wasn't exactly right, but they got the ball rolling.  Then Reinhold jumped
in and developed the base code, and I developed the ellipse and oval code,
and all of a sudden the harp pedals were implemented.

If you want this dependency tree, teach us what you have in mind by
developing part of it yourself (perhaps not even automatically generated).
There are enough people that care about LilyPond that if you get started on
a good feature, I believe it will get implemented (for example, infinitely
nested staff groups, and the new book-part code).  So hack something out and
contribute it to LilyPond.  I'm sure the community would love to have it, if
it's as good as you envision it to be.

One thing I've found out about working with LilyPond -- you don't get very
far by proposing that somebody should do the work to create your great idea.
But you can get a long way by trying to do the work to create your great
idea and then asking for help.

Thanks for your interest in helping improve LilyPond.  I look forward to
seeing some examples of your ideas.

Thanks,

Carl Sorensen





reply via email to

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