7.5 LilyPond Wiki to Git (LilyPond Contributor’s Guide)

### 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.

#### LilyPond Contributor’s Guide v2.26.0 (stable-branch).

- 1 Introduction to contributing
  - 1.1 Help us
  - 1.2 Overview of work flow
  - 1.3 Summary for experienced developers
  - 1.4 Mentors
- 2 Quick start
  - 2.1 LilyDev
    - Installing LilyDev in VirtualBox
    - Configuring LilyDev in VirtualBox
  - 2.2 Compiling with LilyDev
  - 2.3 Now start work!
- 3 Working with source code
  - 3.1 Setting up
    - 3.1.1 Installing Git
    - 3.1.2 Creating a GitLab account and setting up SSH
    - 3.1.3 Cloning and forking the repository
    - 3.1.4 Configuring Git
  - 3.2 Git cheat sheet
  - 3.3 Lifecycle of a merge request
    - 3.3.1 Uploading a patch for review
    - 3.3.2 Automated testing
    - 3.3.3 Patch countdown
    - 3.3.4 Merging to master
    - 3.3.5 Abandoned patches
  - 3.4 Writing good commit messages
  - 3.5 Commit access
  - 3.6 Further Git documentation resources
  - 3.7 Repository directory structure
- 4 Compiling
  - 4.1 Overview of compiling
  - 4.2 Requirements
    - 4.2.1 Requirements for running LilyPond
    - 4.2.2 Requirements for compiling LilyPond
      - Fedora
      - Linux Mint
      - OpenSUSE
      - Ubuntu
      - Other
    - 4.2.3 Requirements for building documentation
  - 4.3 Getting the source code
  - 4.4 Configuring `make`
    - 4.4.1 Build modes
    - 4.4.2 Running `autogen.sh`
    - 4.4.3 Running `configure`
      - Configuration options
      - Checking build dependencies
      - Configuring target directories
  - 4.5 Compiling LilyPond
    - 4.5.1 Using `make`
    - 4.5.2 Saving time with the `-j` option
    - 4.5.3 Useful `make` variables
  - 4.6 Post-compilation options
    - 4.6.1 Installing LilyPond from a local build
    - 4.6.2 Generating documentation
      - Documentation editor’s edit/compile cycle
      - Building documentation
      - Building a single document
      - Saving time with `CPU_COUNT`
      - Installing documentation
      - Building documentation without compiling
    - 4.6.3 Testing LilyPond binary
  - 4.7 Problems
  - 4.8 Concurrent stable and development versions
    - 4.8.1 Replacing the notation fonts in development versions
  - 4.9 Build system
- 5 Documentation work
  - 5.1 Introduction to documentation work
  - 5.2 `\version` in documentation files
  - 5.3 Documentation suggestions
  - 5.4 Texinfo introduction and usage policy
    - 5.4.1 Texinfo introduction
    - 5.4.2 Documentation files
    - 5.4.3 Sectioning commands
    - 5.4.4 Menus
    - 5.4.5 LilyPond formatting
    - 5.4.6 Text formatting
    - 5.4.7 Syntax survey
      - Comments
      - Cross-references
      - External links
      - Fixed-width font
      - Indexing
      - Lists
      - Special characters
      - Miscellany
    - 5.4.8 Other text concerns
  - 5.5 Documentation policy
    - 5.5.1 Books
    - 5.5.2 Section organization
    - 5.5.3 Checking cross-references
    - 5.5.4 General writing
    - 5.5.5 Technical writing style
  - 5.6 Tips for writing documentation
    - 5.6.1 Working on subsections
    - 5.6.2 Searching
  - 5.7 Scripts to ease documentation work
    - 5.7.1 Building only one section of the documentation
    - 5.7.2 Updating documentation with `convert-ly`
  - 5.8 Documentation strings in the Internals Reference
  - 5.9 Translating the documentation
    - 5.9.1 Getting started with documentation translation
      - Translation requirements
      - Which documentation can be translated
      - Starting translation in a new language
    - 5.9.2 Documentation translation details
      - Files to be translated
      - Translating the website and other Texinfo documentation
      - Adding a Texinfo manual
    - 5.9.3 Documentation translation maintenance
      - Check state of translation
      - Updating documentation translation
      - Updating translation committishes
      - Maintaining without updating translations
    - 5.9.4 Technical background
- 6 Website work
  - 6.1 Introduction to website work
  - 6.2 Uploading website
  - 6.3 Debugging website and docs locally
  - 6.4 Translating the website
- 7 LilyPond Wiki work
  - 7.1 Introduction to the LilyPond Wiki
  - 7.2 Adding and editing snippets
  - 7.3 Snippet administration
  - 7.4 The `makelsr.pl` script
  - 7.5 LilyPond Wiki to Git
- 8 Issues
  - 8.1 Introduction to issues
  - 8.2 Triaging bugs
  - 8.3 Issue classification
  - 8.4 Adding issues to the tracker
- 9 Regression tests
  - 9.1 Introduction to regression tests
  - 9.2 Precompiled regression tests
  - 9.3 Compiling regression tests
  - 9.4 Regtest comparison
  - 9.5 Pixel-based regtest comparison
  - 9.6 Finding the cause of a regression
  - 9.7 MusicXML tests
- 10 Programming work
  - 10.1 Overview of LilyPond architecture
  - 10.2 LilyPond programming languages
  - 10.3 Programming without compiling
  - 10.4 Finding functions
  - 10.5 Code style
    - 10.5.1 Languages
    - 10.5.2 Filenames
    - 10.5.3 Code formatting
    - 10.5.4 Naming Conventions
    - 10.5.5 Broken code
    - 10.5.6 Code comments
    - 10.5.7 Handling errors
    - 10.5.8 Localization
  - 10.6 Warnings, Errors, Progress and Debug Output
  - 10.7 Debugging LilyPond
    - 10.7.1 Debugging overview
    - 10.7.2 Debugging C++ code
    - 10.7.3 Debugging Scheme code
    - 10.7.4 Debugging scoring algorithms
    - 10.7.5 Debugging skylines
  - 10.8 Tracing object relationships
  - 10.9 Tracing processing time
  - 10.10 Adding or modifying features
    - 10.10.1 Write the code
    - 10.10.2 Write regression tests
    - 10.10.3 Write convert-ly rule
    - 10.10.4 Automatically update documentation
    - 10.10.5 Manually update documentation
    - 10.10.6 Edit changes.tely
    - 10.10.7 Verify successful build
    - 10.10.8 Verify regression tests
    - 10.10.9 Post patch for comments
    - 10.10.10 Push patch
    - 10.10.11 Closing the issues
  - 10.11 Iterator tutorial
  - 10.12 Engraver tutorial
    - 10.12.1 Useful methods for information processing
    - 10.12.2 Translation process
    - 10.12.3 Listening to music events
    - 10.12.4 Acknowledging grobs
    - 10.12.5 Engraver declaration/documentation
  - 10.13 Callback tutorial
  - 10.14 Understanding pure properties
    - 10.14.1 Purity in LilyPond
    - 10.14.2 Writing a pure function
    - 10.14.3 How purity is defined and stored
    - 10.14.4 Where purity is used
    - 10.14.5 Case studies
    - 10.14.6 Debugging tips
  - 10.15 LilyPond scoping
  - 10.16 Regular expressions
  - 10.17 Scheme->C interface
    - 10.17.1 Comparison
    - 10.17.2 Conversion
  - 10.18 Garbage collection for dummies
  - 10.19 LilyPond miscellany
    - 10.19.1 Spacing algorithms
    - 10.19.2 Info from Han-Wen email
    - 10.19.3 Music functions and Guile debugging
    - 10.19.4 Articulations on EventChord
- 11 Release work
  - 11.1 Development phases
  - 11.2 Release checklist
  - 11.3 Major release checklist
- 12 Modifying the Emmentaler font
  - 12.1 Overview of the Emmentaler font
  - 12.2 Font creation tools
  - 12.3 Adding a new font section
  - 12.4 Adding a new glyph
  - 12.5 Building the changed font
  - 12.6 METAFONT formatting rules
- 13 Administrative policies
  - 13.1 LilyPond is GNU Software
  - 13.2 Environment variables
  - 13.3 Performing yearly copyright update (“grand-replace”)
- Appendix A GNU Free Documentation License