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--
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
