Re: multiple issues with building docs (patch included)

[Graham Percival]

On Wed, Nov 02, 2011 at 04:20:02PM +0000, Adam Spiers wrote:
> On Wed, Nov 2, 2011 at 5:25 AM, Graham Percival
> <address@hidden> wrote:
> > I'm not certain about the
> > big-page, but
> >  make out=www out-www/notation/index.html
> > should be no problem.
> 
> IIRC I tried that, and it seemed to behave as a NOOP - do the
> makefiles register dependencies on index.html for all the subsections?

Well, they're supposed to.  Julien did a lot of work on this in
the past few weeks, and he knows what he's doing.  It's not
impossible that something slipped through the cracks, though.

hmm, maybe the images (or directory symlinks, maybe) are only
dealt with properly in the post-processing step.  That would mean
that you can do the "single manual" make (above) to *update* your
documentation, but not to build it initially.


> > yep.  Well, $LILYPOND_GIT/build/
> 
> Please see my comment on the above issue - any reason to prefer use of
> this environment variable over auto-detection even where it is easily
> achievable?

In general, I prefer to have a single point of failure -- if
somebody doesn't have their env vars set up correctly, I'd rather
have a whole bunch of things fail at once, instead of just one or
two things failing (and possibly being easier to miss).

That said, in this case I'm fine with the auto-detection.

> > after about 2 months of debate, we've adopted
> > http://lilypond.org/~graham/gop/gop_9.html
> > but not much work has gone into implementing it yet.
> 
> Ahah!  Looks very promising.

oops, better link here:
http://lilypond.org/doc/v2.15/Documentation/contributor/policy-decisions-_0028finished_0029

Previous link is for the "in progress" stuff; the CG link is for
completed discussions, including links to important email threads
if you want to get a sense of just how much time and effort we've
spent on this stuff.

> > Incidently, you may want to browse the proposals:
> > http://lilypond.org/~graham/gop/index.html
> > to see what kind of mess we're in.
> 
> Wow.  There sure is a lot to do, but I certainly wouldn't call it a
> mess; in fact I think this is probably the most thoughtfully organized
> F/OSS project I've ever seen, and way better than many commercial
> ventures.

At this very moment,
- we cannot build releases
- we are not merging dev/staging with master
- we are not testing new patches for review
- we have no dedicated person helping new contributors
- we have not trained any new bug handlers in the past 12 months
  (or more); highly skilled developers are handling all bug reports
- we have not imported LSR to git since summer
- I am too sick to be civil until mid-Dec:
http://lists.gnu.org/archive/html/lilypond-devel/2011-10/msg00402.html

sure, there's a lot of potential in lilypond, and we were doing
great over the summer, but things are a complete mess right now.


> OK, I've changed it to honour three environment variables:
> 
>    LILYPOND_GIT         (auto-detects if not set)
>    LILYPOND_BUILD_DIR   (defaults to $LILYPOND_GIT/build)
>    LILYPOND_TEMPDOCS    (defaults to $LILYPOND_BUILD_DIR/tempdocs)
> 
> Is that better?  I've also adapted cg-section.sh in exactly the same
> way.  Patch below ...

Sure, LGTM.

> > Thanks so much for the patch to our development stuff, though!  I
> > can't honestly recommend that anybody get involved in lilypond
> > development at the moment, but it's great to see people still
> > trying to do it and making the process easier for the "next
> > generation".
> 
> Hah :-) As with your other mails, I really appreciate your honesty.
> It would be far more disheartening to feel I was being tricked into
> spending unexpected amounts of time on climbing a steep learning curve
> without adequate support.

ok, that's a relief.  My biggest concern is people doing a lot of
work, expecting to have a certain amount of gratitude and support,
and then getting disappointed a few weeks later when they don't
get the help they think they deserve.  I'd rather drive away half
our potential volunteers instead of seeing yet more people getting
stuck and bailing with bad feelings.  Since you clearly know what
you're getting into: welcome.

- Graham