7.5 Fixing snippets in LilyPond sources

If some snippet from ‘Documentation/snippets’ causes the documentation compilation to fail, the following steps should be followed to fix it reliably.

1. Look up the snippet filename ‘foo.ly’ in the error output or log, then fix the file ‘Documentation/snippets/foo.ly’ to make the documentation build successfully.
2. Determine where it comes from by looking at its first two lines, e.g. run

   head -2 Documentation/snippets/foo.ly

3. If the snippet comes from the LSR, also apply the fix to the snippet in the LSR and send a notification email to an LSR editor with CC to the development list – see Adding and editing snippets. The failure may sometimes not be caused by the snippet in LSR but by the syntax conversion made by convert-ly; in this case, try to fix convert-ly or report the problem on the development list, then run makelsr.py again, see LSR to Git. In some cases, when some features has been introduced or vastly changed so it requires (or takes significant advantage of) important changes in the snippet, it is simpler and recommended to write a new version of the snippet in ‘Documentation/snippets/new’, then run makelsr.py.
4. If the snippet comes from ‘Documentation/snippets/new’, apply the fix in ‘Documentation/snippets/new/foo.ly’, then run makelsr.py without argument from top of the source tree:

   scripts/auxiliar/makelsr.py

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

   If the build failure was caused by a translation string, you may have to fix some ‘Documentation/lang/texidocs/foo.texidoc’ instead; in case the build failure comes only from translation strings, it is not needed to run makelsr.py.

5. When you’ve done, commit your changes to Git and ensure they’re pushed to the correct branch.

This document was generated by gub on July 13, 2020 using texi2html 1.82.