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
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
+
+According to
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1236,Lilypond issue 1236},
+the location of the lilypond git tree is taken from @code{$LILYPOND_GIT}
+if specified, otherwise it is auto-detected.
+
+It is assumed that compilation takes place in the @file{build/}
+subdirectory, but this can be overridden by setting the environment
+variable @code{LILYPOND_BUILD_DIR}.
+
+Similarly, output defaults to @file{build/tempdocs/} but this can be
+overridden by setting the environment variable
+@code{LILYPOND_TEMPDOCS}.
+
This script will not work for building sections of the
Contributors' guide. For building sections of the Contributors'
Guide, use:
scripts/auxiliar/cg-section.sh doc-work
@end example
-Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
-for your installation.
+@code{cg-section.sh} uses the same environment variables and
+corresponding default values as @code{doc-section.sh}.
@subheading Stripping whitespace and generating menus
# Build html versions of sections of lilypond Contributors' Guide
#
-# Usage: cg-section.sh SECTION
+# Usage: ./cg-section.sh SECTION
#
-# where SECTION is the section to be built.
+# where SECTION is the section to be built.
#
-# For example, CG 4 would be built by
-# cg-section.sh doc-work
+# For example, CG 4 would be built by
+# ./cg-section.sh doc-work
#
-# At the end of the run, the user is prompted whether or not to remove files
+# At the end of the run, the user is prompted whether or not to
+# remove the generated files.
#
-# Before first use, the following must be done:
-# * Set FROMDIR, DOCDIR, TODIR, LILYPONDBOOK, and TEXI2HTML for your system
-# * Create $DOCDIR
-# * Copy version.itexi from somewhere in your Documentation tree
-# (probably Documentation/out) to $DOCDIR
+# Paths are calculated from environment variables in exactly the
+# same way as they are for doc-section.sh - see the documentation
+# for that.
#
# Known limitations:
#
# * Bitmap images aren't loaded properly
#
-#
-# Customize the file here
-#
-FROMDIR="$HOME/lilypond"
-DOCDIR="$HOME/lilypond/tempdocs"
-TODIR="$DOCDIR/contributor"
+usage () {
+ cat <<EOF >&2
+Usage: $0 SECTION
+
+e.g. $0 doc-work
+EOF
+ exit "$1"
+}
+
+if [ "$1" == '-h' ] || [ "$1" == '--help' ]; then
+ usage 0
+fi
+
+[ $# = 1 ] || usage 1
+
+if [ -n "$LILYPOND_GIT" ]; then
+ echo "Using source tree from value of \$LILYPOND_GIT: $LILYPOND_GIT"
+else
+ cd "`dirname $0`"
+ cd ../..
+ LILYPOND_GIT="`pwd`"
+ echo "\$LILYPOND_GIT was not set; auto-detected source tree at $LILYPOND_GIT"
+fi
+
+if test ! -e "$LILYPOND_GIT/DEDICATION"; then
+ echo "Error: $LILYPOND_GIT did not look like a LilyPond source tree; aborting." >&2
+ exit 1
+fi
+
+: "${LILYPOND_BUILD_DIR:=$LILYPOND_GIT/build}"
+DOC_DIR="${LILYPOND_TEMPDOCS:-$LILYPOND_BUILD_DIR/tempdocs}"
+LILYPOND_BOOK="$LILYPOND_BUILD_DIR/out/bin/lilypond-book"
TEXI2HTML="texi2html"
-REFCHECK="$FROMDIR/scripts/auxiliar/ref_check.py"
+REFCHECK="$LILYPOND_GIT/scripts/auxiliar/ref_check.py"
-NAME=$1
+SECTION="$1"
+DOCDIR="$HOME/lilypond/tempdocs"
+OUTPUT_DIR="$DOC_DIR/contributor"
+SECTION_PATH="$LILYPOND_GIT/Documentation/contributor/$SECTION.itexi"
-if test ! -d $TODIR; then
- mkdir $TODIR
+if test ! -e "$SECTION_PATH"; then
+ echo "$SECTION_PATH did not exist; is $SECTION a valid section in the Contributor's Guide?" >&2
+ exit 1
fi
-if test ! -d $TODIR/out; then
- mkdir $TODIR/out
+
+if test ! -d "$OUTPUT_DIR"; then
+ mkdir "$OUTPUT_DIR"
+fi
+if test ! -d "$OUTPUT_DIR/out"; then
+ mkdir "$OUTPUT_DIR/out"
fi
-cp $FROMDIR/Documentation/common-macros.itexi $TODIR/common-macros.itexi
-cp $FROMDIR/Documentation/macros.itexi $DOCDIR/macros.itexi
-cp $DOCDIR/version.itexi $TODIR/version.itexi
+cp "$LILYPOND_GIT/Documentation/common-macros.itexi" "$OUTPUT_DIR/common-macros.itexi"
+cp "$LILYPOND_GIT/Documentation/macros.itexi" "$DOC_DIR/macros.itexi"
+cp "$LILYPOND_BUILD_DIR/Documentation/out/version.itexi" "$OUTPUT_DIR"
-if test -e $TODIR/$NAME.html; then
- rm $TODIR/$NAME.html
+if test -e "$OUTPUT_DIR/$SECTION.html"; then
+ rm "$OUTPUT_DIR/$SECTION.html"
fi
-if test -e $TODIR/out/$NAME.texi; then
- rm $TODIR/out/$NAME.texi
+if test -e "$OUTPUT_DIR/out/$SECTION.texi"; then
+ rm "$OUTPUT_DIR/out/$SECTION.texi"
fi
-echo Running RefCheck
-python $REFCHECK
+echo "Running RefCheck"
+python "$REFCHECK"
+
+cd "$DOC_DIR"
+echo "Running $TEXI2HTML"
+cat "$DOC_DIR/macros.itexi" "$SECTION_PATH" > "$OUTPUT_DIR/$SECTION.texi"
+
+"$TEXI2HTML" \
+ --no-validate \
+ --output="$OUTPUT_DIR/out/$SECTION.html" \
+ --I="$LILYPOND_GIT/Documentation" \
+ --I="$OUTPUT_DIR/out" \
+ "$OUTPUT_DIR/$SECTION.texi"
+
+cat <<EOF
+
+The $SECTION section of the Contributor's Guide should now be viewable at
+
+ $OUTPUT_DIR/out/$SECTION.html
+
+If you want to keep the generated docs around for a while, answer
+'n' to the next question. If you only needed them to quickly check
+something, view them now and then answer 'y' when you're done.
-cd $DOCDIR
-echo Running texi2html
-cat $DOCDIR/macros.itexi $FROMDIR/Documentation/contributor/$NAME.itexi > $TODIR/$NAME.texi
-$TEXI2HTML \
- --no-validate \
- --output=$TODIR/out/$NAME.html \
- --I=$FROMDIR/Documentation \
- --I=$TODIR/out \
- $TODIR/$NAME.texi
+EOF
-read -p "delete files? (y/n): "
+read -p "rm -rf $OUTPUT_DIR ? (y/n): "
if [ "$REPLY" = "y" ]; then
- echo "deleting files"
- rm -rf $TODIR
+ echo "deleting files"
+ rm -rf "$OUTPUT_DIR"
fi
# Build html versions of sections of lilypond documentation
#
-# Usage: doc-section.sh MANUAL SECTION
+# Usage: ./doc-section.sh MANUAL SECTION
#
-# where MANUAL is the manual and SECTION is the section to be built.
+# where MANUAL is the manual and SECTION is the section to be
+# built.
#
-# For example, NR 1.2 would be built by
-# doc-section.sh notation rhythms
+# For example, NR 1.2 would be built by
+# ./doc-section.sh notation rhythms
#
# and LM 1 would be built by
-# doc-section.sh learning tutorial
+# ./doc-section.sh learning tutorial
#
-# At the end of the run, the user is prompted whether or not to remove files
+# At the end of the run, the user is prompted whether or not to
+# remove the generated files.
+#
+# According to http://code.google.com/p/lilypond/issues/detail?id=1236
+# the location of the lilypond git tree is taken from $LILYPOND_GIT
+# if specified, otherwise it is auto-detected.
+#
+# It is assumed that compilation takes place in the build/
+# subdirectory, but this can be overridden by setting the environment
+# variable LILYPOND_BUILD_DIR.
+#
+# Similarly, output defaults to build/tempdocs/ but this can be
+# overridden by setting the environment variable LILYPOND_TEMPDOCS.
#
-# Before first use, the following must be done:
-# * Set FROMDIR, DOCDIR, TODIR, LILYPONDBOOK, and TEXI2HTML for your system
-# * Create $DOCDIR
-# * Copy version.itexi from somewhere in your Documentation tree
-# (probably Documentation/out) to $DOCDIR
#
# Known limitations:
#
# * 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"
+usage () {
+ cat <<EOF >&2
+Usage: $0 MANUAL SECTION
+
+e.g. $0 notation rhythms
+EOF
+ exit "$1"
+}
+
+if [ "$1" == '-h' ] || [ "$1" == '--help' ]; then
+ usage 0
+fi
+
+[ $# = 2 ] || usage 1
+
+if [ -n "$LILYPOND_GIT" ]; then
+ echo "Using source tree from value of \$LILYPOND_GIT: $LILYPOND_GIT"
+else
+ cd "`dirname $0`"
+ cd ../..
+ LILYPOND_GIT="`pwd`"
+ echo "\$LILYPOND_GIT was not set; auto-detected source tree at $LILYPOND_GIT"
+fi
+
+if test ! -e "$LILYPOND_GIT/DEDICATION"; then
+ echo "Error: $LILYPOND_GIT did not look like a LilyPond source tree; aborting." >&2
+ exit 1
+fi
+
+: "${LILYPOND_BUILD_DIR:=$LILYPOND_GIT/build}"
+DOC_DIR="${LILYPOND_TEMPDOCS:-$LILYPOND_BUILD_DIR/tempdocs}"
+LILYPOND_BOOK="$LILYPOND_BUILD_DIR/out/bin/lilypond-book"
TEXI2HTML="texi2html"
-REFCHECK="$FROMDIR/scripts/auxiliar/ref_check.py"
+REFCHECK="$LILYPOND_GIT/scripts/auxiliar/ref_check.py"
-DIRECTORY=$1
-NAME=$2
-TODIR=$DOCDIR/$NAME
+MANUAL="$1"
+SECTION="$2"
+OUTPUT_DIR="$DOC_DIR/$SECTION"
+MANUAL_PATH="$LILYPOND_GIT/Documentation/$MANUAL"
+SECTION_PATH="$MANUAL_PATH/$SECTION.itely"
-if test ! -d $TODIR; then
- mkdir $TODIR
+if test ! -d "$LILYPOND_BUILD_DIR"; then
+ echo "$LILYPOND_BUILD_DIR did not exist; check your setting of LILYPOND_BUILD_DIR. Aborting." >&2
+ exit 1
fi
-if test ! -d $TODIR/out; then
- mkdir $TODIR/out
+
+if test ! -d "$MANUAL_PATH"; then
+ echo "$MANUAL_PATH was not a valid directory; is $MANUAL a valid manual?" >&2
+ exit 1
+fi
+
+if test ! -e "$SECTION_PATH"; then
+ echo "$SECTION_PATH did not exist; is $SECTION a valid section in the $MANUAL manual?" >&2
+ exit 1
+fi
+
+if test ! -d "$DOC_DIR"; then
+ mkdir "$DOC_DIR"
+ cp "$LILYPOND_BUILD_DIR/Documentation/out/version.itexi" "$DOC_DIR"
+fi
+if test ! -d "$OUTPUT_DIR"; then
+ mkdir "$OUTPUT_DIR"
+fi
+if test ! -d "$OUTPUT_DIR/out"; then
+ mkdir "$OUTPUT_DIR/out"
fi
-cp $FROMDIR/Documentation/common-macros.itexi $TODIR/common-macros.itexi
-cp $FROMDIR/Documentation/macros.itexi $DOCDIR/macros.itexi
-cp $DOCDIR/version.itexi $TODIR/version.itexi
+cp "$LILYPOND_GIT/Documentation/common-macros.itexi" "$OUTPUT_DIR/common-macros.itexi"
+cp "$LILYPOND_GIT/Documentation/macros.itexi" "$DOC_DIR/macros.itexi"
+cp "$DOC_DIR/version.itexi" "$OUTPUT_DIR/version.itexi"
-if test -e $TODIR/$NAME.html; then
- rm $TODIR/$NAME.html
+if test -e "$OUTPUT_DIR/$SECTION.html"; then
+ rm "$OUTPUT_DIR/$SECTION.html"
fi
-if test -e $TODIR/out/$NAME.texi; then
- rm $TODIR/out/$NAME.texi
+if test -e "$OUTPUT_DIR/out/$SECTION.texi"; then
+ rm "$OUTPUT_DIR/out/$SECTION.texi"
fi
-echo "Running lilypond-book"
-$LILYPONDBOOK \
+echo "Running $LILYPOND_BOOK"
+"$LILYPOND_BOOK" \
-f texi-html \
- -I $FROMDIR/Documentation/snippets \
- -I $FROMDIR/Documentation/snippets/new \
- -I $FROMDIR/input/manual \
- -I $FROMDIR/Documentation \
- -I $FROMDIR/Documentation/included \
- -I $FROMDIR/Documentation/pictures \
- -o $TODIR/out \
- $FROMDIR/Documentation/$DIRECTORY/$NAME.itely
+ -I "$LILYPOND_GIT/Documentation/snippets" \
+ -I "$LILYPOND_GIT/Documentation/snippets/new" \
+ -I "$LILYPOND_GIT/input/manual" \
+ -I "$LILYPOND_GIT/Documentation" \
+ -I "$LILYPOND_GIT/Documentation/included" \
+ -I "$LILYPOND_GIT/Documentation/pictures" \
+ -o "$OUTPUT_DIR/out" \
+ "$SECTION_PATH"
BOOKRC=$?
-if [ $BOOKRC != 0 ]; then
- echo "Lilypond-book returned code $BOOKRC"
- exit $BOOKRC
+if [ "$BOOKRC" != 0 ]; then
+ echo "Lilypond-book returned code $BOOKRC"
+ exit $BOOKRC
fi
-echo Running RefCheck
-python $REFCHECK
-
-cd $DOCDIR
-if test -f $TODIR/out/$NAME.texi; then
- echo Running texi2html
- cat $DOCDIR/macros.itexi $TODIR/out/$NAME.texi > $TODIR/$NAME.texi
- $TEXI2HTML \
- --no-validate \
- --output=$TODIR/out/$NAME.html \
- --I=$TODIR/out \
- $TODIR/$NAME.texi
+echo "Running RefCheck"
+python "$REFCHECK"
+
+cd "$DOC_DIR"
+if test -f "$OUTPUT_DIR/out/$SECTION.texi"; then
+ echo "Running $TEXI2HTML"
+ cat "$DOC_DIR/macros.itexi" "$OUTPUT_DIR/out/$SECTION.texi" > "$OUTPUT_DIR/$SECTION.texi"
+ "$TEXI2HTML" \
+ --no-validate \
+ --output="$OUTPUT_DIR/out/$SECTION.html" \
+ --I="$OUTPUT_DIR/out" \
+ "$OUTPUT_DIR/$SECTION.texi"
fi
-read -p "delete files? (y/n): "
+cat <<EOF
+
+The $SECTION section of the $MANUAL manual should now be viewable at
+
+ $OUTPUT_DIR/out/$SECTION.html
+
+If you want to keep the generated docs around for a while, answer
+'n' to the next question. If you only needed them to quickly check
+something, view them now and then answer 'y' when you're done.
+
+EOF
+
+read -p "rm -rf $OUTPUT_DIR ? (y/n): "
if [ "$REPLY" = "y" ]; then
- echo "deleting files"
- rm -rf $TODIR
+ echo "deleting files"
+ rm -rf "$OUTPUT_DIR"
fi
projects / lilypond.git / commitdiff