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-documentation#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 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-doc-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. 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 Couldn't this simply be included in the script rather than as an extra step in the instructions? 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 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" and now it seems to work, albeit with this mysterious-looking prompt at the end of the run: delete files? (y/n): 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 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" +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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
