Re: multiple issues with building docs (patch included)

[Graham Percival]

On Wed, Nov 02, 2011 at 02:14:13AM +0000, Carl Sorensen wrote:
> 
> On 11/1/11 5:44 PM, "Adam Spiers" <address@hidden> wrote:
> 
> >`make doc' works, but takes too long to be of practical use except as
> >a final sanity check before submitting a patch upstream.

You can use multiple threads.

> >http://lilypond.org/doc/v2.15/Documentation/contributor/generating-documen
> >tation#building-a-single-document
> >
> >explains how to build a single document, but only gives a PDF as an
> >example.  I wanted to rebuild the split-page HTML version of the
> >Notation Reference, but couldn't figure out how.  Instead I managed to
> >build the big page version via:
> >
> >  make out=www out-www/notation-big-page.html
>
> AFAICS, the single manual doc build is not really functional.

Nonsense, it should be perfectly fine.  I'm not certain about the
big-page, but
  make out=www out-www/notation/index.html
should be no problem.

> >    This script will require customization for your site if your
> >    LilyPond git repository is anyplace but $HOME/lilypond.
> 
> Lilypond-git is the canonical location now, instead of lilypond.  If
> scripts/auxiliar/doc-section.sh does not refer to liypond-git, it should
> be fixed.

http://code.google.com/p/lilypond/issues/detail?id=1236

been on the books for over a year.

> >When building in a build/ subdirectory as recommended by the Guide,
> >this path is wrong; it should be:
> >
> >    cp $LILYPOND/build/Documentation/out/version.itexi
> >$HOME/lilypond/tempdocs
> 
> Actually, the script should be changed to refer to
> $LILYPOND/build/tempdocs.

yep.  Well, $LILYPOND_GIT/build/

> >Couldn't this simply be included in the script rather than as an extra
> >step in the instructions?
> 
> It certainly could.

yep.

> >"/home/adam/lilypond-git/tempdocs/chords/out/snippet-names--514510028.ly"
> >Child returned 1
> >Lilypond-book returned code 1
> 
> Now you are running into the key challenge for building docs.
> 
> If you run
> 
> Lilypond tempdocs/out/e5/lily-0f1202dd.ly, you'll get to see the error
> message.  In fact, there's probably a logfile in tempdocs/out/e5 that has
> the error message.

or you could just look at tempdocs/out/e5/lily-0f1202dd.ly ,
delete a few lines from it so you can compile it on the
command-line, then debug that.

> >I'm not sure how to debug this because there doesn't seem to be a
> >useful error either on STDOUT or in a log file anywhere.

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

Incidently, you may want to browse the proposals:
http://lilypond.org/~graham/gop/index.html
to see what kind of mess we're in.

> >Having said
> >that, the fact that it's using /usr/bin/lilypond rather than my
> >locally compiled version is highly suspect.

wow, yes.  That'll be the cause.

> >Finally, tempdocs is not in .gitignore.

doc-section.sh isn't really supported, and in any case I would
personally set tempdocs to be /tmp/ramdisk/lily-quick-docs or
something like that... so I'm not keen on that change.


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

- Graham