Re: multiple issues with building docs (patch included)

[Carl Sorensen]

On 11/1/11 5:44 PM, "Adam Spiers" <address@hidden> wrote:

>I'm trying to make sure my patches include the right tweaks to the
>documentation, but as a newbie to lilypond development (but with a lot
>of development experience elsewhere), I'm sorry to say I'm really
>struggling :-(
>
>`make doc' works, but takes too long to be of practical use except as
>a final sanity check before submitting a patch upstream.
>
>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.

>
>but the images are missing, so that's no use to me.  I also found
>
>http://lilypond.org/doc/v2.15/Documentation/contributor/scripts-to-ease-do
>c-work
>
>which pointed me to scripts/auxiliar/doc-section.sh, but this had
>multiple issues.  Firstly, the Contributor's Guide says:
>
>    This script will require customization for your site if your
>    LilyPond git repository is anyplace but $HOME/lilypond.
>
>Customizing the script is problematic, because that introduces
>non-commitable changes to a file tracked by git.  Adding a symlink
>from ~/lilypond doesn't work either, because commit
>c9ae4b4db5e9e147b9eebb68264f0d9928dca39a changed the location to
>~/lilypond-git.


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.


>
>Another oddity in the Guide is where it tells you to do:
>
>    cp $HOME/lilypond/Documentation/out/version.itexi
>$HOME/lilypond/tempdocs
>
>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.

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

It certainly could.

>
>Anyway, after symlinking from ~/lilypond-git, I could successfully
>run doc-section.sh, but then it inexplicably fails during the run:
>
>Writing e6/lily-95d83000-systems.texi...
>Writing e6/lily-95d83000-systems.tex...
>Writing e6/lily-95d83000-systems.count...
>error: failed files: "e5/lily-0f1202dd.ly"
>command failed: /usr/bin/lilypond --formats=ps,png -dbackend=eps  -I
>"/home/adam/.GIT/3rd-party/lilypond.git"  -I
>"/home/adam/lilypond-git/Documentation/snippets"  -I
>"/home/adam/lilypond-git/Documentation/snippets/new"  -I
>"/home/adam/lilypond-git/input/manual"  -I
>"/home/adam/lilypond-git/Documentation"  -I
>"/home/adam/lilypond-git/Documentation/included"  -I
>"/home/adam/lilypond-git/Documentation/pictures" --formats=eps
>-deps-box-padding=3.000000  -dread-file-list -dno-strip-output-dir
>"/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.


>
>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.  Having said
>that, the fact that it's using /usr/bin/lilypond rather than my
>locally compiled version is highly suspect.  I see that doc-section.sh
>contains:
>
>    LILYPONDBOOK="lilypond-book"
>
>which picks up /usr/bin/lilypond-book.  I changed it to
>
>    LILYPONDBOOK="$FROMDIR/build/out/bin/lilypond-book"

This is a good change to the file.  I have /usr/bin/lilypond-book
symlinked to my local build directory, because I don't run an installed
version of lilypond.  So it's my fault that the script was wrong.  Thanks
for the catch.

>
>and now it seems to work, albeit with this mysterious-looking prompt
>at the end of the run:
>
>    delete files? (y/n):

If you answer y, all the new files will be deleted.  If you answer n,
they¹ll be left around.  I usually check the output, and once it's good, I
hit y.

>
>Finally, tempdocs is not in .gitignore.
>
>Here is a patch which fixes all the issues in this email:
>
>From 3bb0571c8322d6da8e546955966952427f2ee6c2 Mon Sep 17 00:00:00 2001
>From: Adam Spiers <address@hidden>
>Date: Tue, 1 Nov 2011 23:35:00 +0000
>Subject: [PATCH] Fix several issues regarding
>scripts/auxiliar/doc-section.sh
>
>---
> .gitignore                               |    1 +
> Documentation/contributor/doc-work.itexi |   25 ++++++----------------
> scripts/auxiliar/doc-section.sh          |   32
>+++++++++++++++++++++--------
> 3 files changed, 31 insertions(+), 27 deletions(-)
>
>diff --git a/.gitignore b/.gitignore
>index e0fae2d..19a472c 100644
>--- a/.gitignore
>+++ b/.gitignore
>@@ -78,3 +78,4 @@ Documentation/lilypond
> semantic.cache
> .lock-wscript
> build/
>+/tempdocs

Don't do this -- do move it to build.
>diff --git a/Documentation/contributor/doc-work.itexi
>b/Documentation/contributor/doc-work.itexi
>index 9f42e45..0aabc71 100644
>--- a/Documentation/contributor/doc-work.itexi
>+++ b/Documentation/contributor/doc-work.itexi
>@@ -1416,24 +1416,7 @@ In order to save build time, a script is
>available to build only
> one section of the documentation in English with a default html
> appearance.
>
>-The script is available as:
>-
>address@hidden
>-scripts/auxiliar/doc-section.sh
>address@hidden example
>-
>-This script will require customization for your site if your
>-LilyPond git repository is anyplace but @code{$HOME/lilypond}.
>-
>-Assuming that no customization is required, you can setup the
>-single section build with:
>-
>address@hidden
>-mkdir $HOME/lilypond/tempdocs
>-cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs
>address@hidden example
>-
>-You can then build a section of the documentation with:
>+You can build a section of the documentation with:
>
> @example
> scripts/auxiliar/doc-section.sh MANUAL SECTION
>@@ -1449,6 +1432,12 @@ Notation Reference, use the command:
> scripts/auxiliar/doc-section.sh notation pitches
> @end example
>
>+You can then see the generated document for the section at
>+
>address@hidden
>+tempdocs/pitches/out/pitches.html
>address@hidden example
>+
> This script will not work for building sections of the
> Contributors' guide.  For building sections of the Contributors'
> Guide, use:
>diff --git a/scripts/auxiliar/doc-section.sh
>b/scripts/auxiliar/doc-section.sh
>index 58a272e..af55e23 100755
>--- a/scripts/auxiliar/doc-section.sh
>+++ b/scripts/auxiliar/doc-section.sh
>@@ -27,12 +27,14 @@
> #     * Won't build Contributors' Guide; see
>scripts/auxiliar/cg-section.sh
> #
>
>-#
>-#  Customize the file here
>-#
>-FROMDIR="$HOME/lilypond-git"
>-DOCDIR="$HOME/lilypond-git/tempdocs"
>-LILYPONDBOOK="lilypond-book"
>+cd "`dirname $0`"
>+cd ../..
>+LILY_SRC_DIR="`pwd`"
>+
>+BUILDDIR="$LILY_SRC_DIR/build"
>+FROMDIR="$LILY_SRC_DIR"
>+DOCDIR="$LILY_SRC_DIR/tempdocs"
$BUILDDIR/tempdocs

>+LILYPONDBOOK="$BUILDDIR/out/bin/lilypond-book"
> TEXI2HTML="texi2html"
> REFCHECK="$FROMDIR/scripts/auxiliar/ref_check.py"
>
>@@ -40,6 +42,18 @@ DIRECTORY=$1
> NAME=$2
> TODIR=$DOCDIR/$NAME
>
>+if test ! -d $BUILDDIR; then
>+  cat <<EOF >&2
>+This script assumes that you compile within a build/ subdirectory of your
>+source tree, as recommended by the Contributor's Guide.
>+EOF
>+  exit 1
>+fi
>+
>+if test ! -d $DOCDIR; then
>+  mkdir $DOCDIR
>+  cp $BUILDDIR/Documentation/out/version.itexi $DOCDIR
>+fi
> if test ! -d $TODIR; then
>   mkdir $TODIR
> fi
>@@ -59,7 +73,7 @@ if test -e $TODIR/out/$NAME.texi; then
>   rm $TODIR/out/$NAME.texi
> fi
>
>-echo "Running lilypond-book"
>+echo "Running $LILYPONDBOOK"
> $LILYPONDBOOK \
>         -f texi-html \
>         -I $FROMDIR/Documentation/snippets \
>@@ -71,7 +85,7 @@ $LILYPONDBOOK \
>         -o $TODIR/out \
>         $FROMDIR/Documentation/$DIRECTORY/$NAME.itely
> BOOKRC=$?
>-if [ $BOOKRC != 0 ]; then
>+if [ "$BOOKRC" != 0 ]; then
>   echo "Lilypond-book returned code $BOOKRC"
>   exit $BOOKRC
> fi
>@@ -90,7 +104,7 @@ if test -f $TODIR/out/$NAME.texi; then
>     $TODIR/$NAME.texi
> fi
>
>-read -p "delete files? (y/n): "
>+read -p "rm -rf $TODIR ? (y/n): "
> if [ "$REPLY" = "y" ]; then
>   echo "deleting files"
>   rm -rf $TODIR
>-- 
>1.7.6.4


Thanks for working on this!  I'm sorry that it was so much of a kludge;
you've really improved the script.  If you'd make the change to move
tempdocs to build, I'll be happy to push this patch.

Thanks,

Carl

>