On 11/1/11 5:44 PM, "Adam Spiers" <lilypond-de...@adamspiers.org> 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 <lilypond-fr...@adamspiers.org> >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: >- >-@example >-scripts/auxiliar/doc-section.sh >-@end 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: >- >-@example >-mkdir $HOME/lilypond/tempdocs >-cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs >-@end 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 >+ >+@example >+tempdocs/pitches/out/pitches.html >+@end 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 > _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
