7.5 LilyPond Wiki to Git

Snippets used in the documentation are located in $LILYPOND_GIT/Documentation/snippets/. This directory contains a set of all snippets in the LilyPond Wiki that are tagged with the category ‘Category:Included in the official documentation’. An import is done with the makelsr.pl script, which downloads all documentation snippets from the Wiki to update this directory.

Snippets that need a newer LilyPond version than the current stable release are located in directory $LILYPOND_GIT/Documentation/snippets/new/. Once LilyPond gets upgraded to the next stable version that can actually compile them, they are transferred to the Wiki and deleted from snippets/new/.

‘Git’ is the shorthand name for LilyPond’s git repository, which contains all the development code. For further information on setting this up, see Working with source code. An alternative to setting up a git repository for people wanting to do LilyPond Wiki work is to get the source code from https://lilypond.org/development.html. However, we don’t recommend this since it doesn’t allow easy submission of patches as merge requests.

Importing the LilyPond Wiki into Git

1. Make sure that the convert-ly script is a bleeding edge version – the latest development release, or even better, freshly compiled from git master, with the environment variable LILYPOND_BUILD_DIR correctly set up (see Environment variables) in case your build directory isn’t $LILYPOND_GIT/build/.
2. Check the other prerequisites necessary for executing the makelsr.pl script (see The makelsr.pl script).
3. If you are using a git repository, create and check out a branch, for example

   git checkout -b wiki-import
   

4. From the top source directory, execute

   scripts/auxiliar/makelsr.pl --diff-version-update
   

   Say ‘scripts/auxiliar/makelsr.pl --help’ to find out how to modify this call; for example, command-line option --dump makes the script create a dump file of the Wiki that can be read in a later run with option --input.

5. Carefully check the output of the script for warnings and errors, then carefully check the file differences in the git repository. ‘git diff’ is your friend.
6. Rebuild the documentation. If some snippets from Documentation/snippets/ cause the documentation compilation to fail, try the following steps to fix it.
   • Look up the snippet file name foo.ly in the error output or log file, then fix the file Documentation/snippets/foo.ly to make the documentation build successfully.
   • Determine where the snippet comes from by looking at its first two lines, e.g., run

     head -2 Documentation/snippets/foo.ly
     

   • If the snippet comes from the LilyPond Wiki, also apply the fix to the snippet in the Wiki, see Adding and editing snippets.

     Note that the failure may sometimes not be caused by the snippet in the Wiki but by LilyPond syntax changes that convert-ly can’t handle automatically. Such files must be added to the new/ directory.

   • If the snippet comes from directory Documentation/snippets/new/, apply the fix in Documentation/snippets/new/foo.ly and run makelsr.pl as follows:

     scripts/auxiliar/makelsr.pl --new
     

     Then, inspect Documentation/snippets/foo.ly to check that the fix has been propagated correctly.

   • If the build failure was caused by a translation string, you may have to fix some Documentation/lang/texidocs/foo.texidoc files instead.
7. When you are done, commit your changes to your git branch and create a merge request (see Lifecycle of a merge request).

Below is a simple shell script to process all .ly files in a directory sequentially (i.e., no support for parallel execution); this might help you find problems with snippets. If you pass option -s to the script, it runs silently except for reporting failed files. If run with option -c it also executes convert-ly prior to running lilypond. You need to set the LILYPOND_BUILD_DIR environment variable so that the two programs are found.

#!/bin/bash

while getopts sc opt; do
    case $opt in
        s) silent=true ;;
        c) convert=true ;;
    esac
done

param=$ if [ $silent ]; then
    param=${param:3}
fi
if [ $convert ]; then
    param=${param:3}
fi
filter=${param:-"*.ly"}

for LILYFILE in $filter; do
    STEM=$(basename "$LILYFILE" .ly)
    if [ $convert ]; then
        if [ $silent ]; then
            $LILYPOND_BUILD_DIR/out/bin/convert-ly \
		-e "$LILYFILE" >& "$STEM".con.txt
        else
            $LILYPOND_BUILD_DIR/out/bin/convert-ly \
		-e "$LILYFILE"
        fi
    fi
    if [ ! $silent ]; then
        echo "processing $LILYFILE..."
    fi
    $LILYPOND_BUILD_DIR/out/bin/lilypond \
	--format=png "$LILYFILE" >& "$STEM".txt
    RetVal=$?
    if [ $RetVal -gt 0 ]; then
       echo "$LILYFILE failed"
    fi
done

This script stores logging output from lilypond and convert-ly in files filename.txt and filename.con.txt, respectively.