From: Adam Spiers Date: Wed, 2 Nov 2011 11:13:25 +0000 (+0000) Subject: Usability improvements to {doc,cg}-section.sh and corresponding section of CG. X-Git-Tag: release/2.15.21-1~36 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f955789f0e1726c03b554a9fde21494687ae95b8;p=lilypond.git Usability improvements to {doc,cg}-section.sh and corresponding section of CG. - Now honor LILYPOND_GIT, LILYPOND_BUILD_DIR, and LILYPOND_TEMPDOCS environment variables (all optional). - Provide usage help text if '-h' or '--help' or incorrect arguments are passed. - Output more helpful messages upon completion. --- diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index 9f42e451db..39bd1e1df0 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,25 @@ 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 + +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: @@ -1466,8 +1468,8 @@ 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 diff --git a/scripts/auxiliar/cg-section.sh b/scripts/auxiliar/cg-section.sh index 272260c3c9..77d0bdee96 100755 --- a/scripts/auxiliar/cg-section.sh +++ b/scripts/auxiliar/cg-section.sh @@ -2,20 +2,19 @@ # 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: # @@ -23,51 +22,98 @@ # * Bitmap images aren't loaded properly # -# -# Customize the file here -# -FROMDIR="$HOME/lilypond" -DOCDIR="$HOME/lilypond/tempdocs" -TODIR="$DOCDIR/contributor" +usage () { + cat <&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 < $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 diff --git a/scripts/auxiliar/doc-section.sh b/scripts/auxiliar/doc-section.sh index 58a272e58f..2c6b557a9a 100755 --- a/scripts/auxiliar/doc-section.sh +++ b/scripts/auxiliar/doc-section.sh @@ -2,23 +2,31 @@ # 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: # @@ -27,71 +35,130 @@ # * 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 <&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 <