Re: Documentation of Architecture / Design?

[Douglas A Linhardt]

Han-Wen,

>
> That would be most welcome!
>
> I must admit that when I want to know how a program works, I use grep
> and emacs and dive into the source code. The comments and the code
> itself are usually more revealing than technical documents.
>
> Can you tell me where you started looking and where you lost it?
>
>

Thanks for your response.  Your answers clarified some things and confirmed
other things that I had come across.  I will take your input and organize it a
little better than my original questions and create some HTML pages together
that can be put on the lilypond website (with your permission, of course).

First, let me say that I consider myself a pretty good programmer (I survived
the layoffs at Lucent over the last few years ;) ).  I am very well versed in
C++, so of course, that's where I gravitate first when I look at Lilypond code.
 I am able to follow the Scheme code after reading the R5R, and I have been able
to successfully implement some Scheme hacks as I investigate my autochange
tuning feature.  I have yet to look at Python, but I may have to learn that too,
if that's the way the project is headed (although I'm not looking forward to 
it).

The problem isn't necessarily that I can't find the answers to my questions, but
that it can take hours of searching through code to find a particular
design-level fact.  And by that time, I've pushed and popped so many elements on
my mental stack, that I can't remember how I got there and what I already
dismissed as dead ends.  A roadmap would direct a developer's search for
appropriate code and reduce the learning curve.

Probably the biggest things that threw me are the C++ member functions that are
declared/defined through macros.  It's really annoying when a member function is
not directly declared in the class or one of its ancestors, but in a macro in
some other file completely.  Some documentation of these macros and the "for
free" functions that we get would be nice.

Also, I get lost figuring out what environment the code I'm looking at is in
when it executes.  I found both the C++ and Scheme autochange code.  Then I was
trying to figure out where the code got called from.  I finally figured out that
the Scheme procedure was called before the C++ iterator code, but it took me a
while to figure that out, and I still didn't know who did the calling in the
first place.  I only know a little bit about Flex and Bison, so reading those
files helped only a little bit.

I started my feature by hacking the C++ code, and I was able to use a context
property there.  However, It took me a while to figure out what the split-list
was and where it was created.  I traced down the Scheme file, and I had to tweak
the Scheme code to make sure that 0's weren't being dropped, but I was able to
get my hack to work.

Then I decided that there might be a way to streamline the split-list (I think),
so I decided to try a hack in the Scheme procedure, instead.  But I found out
that I don't have context properties to read there, so I was lost.  How do I get
a user-defined property into the autochange Scheme procedure?  I was going to
use a music property next, but it didn't feel right.  It has taken hours to get
to this point, and I still have this issue to solve.

>>Is anybody interested in helping out on this if I get the ball rolling?
>
>
> Yes! I'll gladly supply answers. I'll start off with your current
> batch of questions. I'm going to give very brief, compact answers, but
> do not hesitate to point out what you don't understand, and ask more,
> so I know where to expand.
>
>

Let me spend some time with what you gave me, and I'll send follow-up questions
when I'm finished with these.  It will probably be a week or so, but I don't
think the information will go out-of-date too quickly ;)

Thanks.

Doug