[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
multiple issues with building docs (patch included)
From: |
Adam Spiers |
Subject: |
multiple issues with building docs (patch included) |
Date: |
Tue, 1 Nov 2011 23:44:19 +0000 |
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 <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
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"
+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
- multiple issues with building docs (patch included),
Adam Spiers <=
- Re: multiple issues with building docs (patch included), Carl Sorensen, 2011/11/01
- Re: multiple issues with building docs (patch included), Graham Percival, 2011/11/02
- Re: multiple issues with building docs (patch included), Adam Spiers, 2011/11/02
- Re: multiple issues with building docs (patch included), Graham Percival, 2011/11/02
- Re: multiple issues with building docs (patch included), David Kastrup, 2011/11/02
- Re: multiple issues with building docs (patch included), Graham Percival, 2011/11/03
- Re: multiple issues with building docs (patch included), David Kastrup, 2011/11/03
- Re: multiple issues with building docs (patch included), Graham Percival, 2011/11/03
- Re: multiple issues with building docs (patch included), David Kastrup, 2011/11/03
- Re: multiple issues with building docs (patch included), Trevor Daniels, 2011/11/03