7.4 The makelsr.pl script

As you might have guessed already, makelsr.pl is a Perl script. Obviously, you need Perl to execute it, which you should now install in case it isn’t already available on your system.

There is a dependency on the pandoc program. The script uses it to convert Wiki pages, which are formatted with MediaWiki Syntax, to the Texinfo format. This program must be installed, too.

Furthermore, makelsr.pl needs a few additional modules that are not Perl core modules:

• File::Which
• IPC::Run3
• Pandoc
• Parallel::ForkManager

Either install missing modules with your package manager (if available) or use the cpanm command.¹⁰

A typical call might me

cpanm --sudo Parallel::ForkManager

to download, compile, and install module ‘Parallel::ForkManager’.¹¹

The --sudo option makes the modules install into a system directory, for example /usr/lib/perl5/site_perl/... – you need the superuser password for this. If you don’t want to do that for whatever reason, just omit --sudo and follow the instructions shown in cpanm’s error message to install Perl modules locally (i.e., without sudo rights).

Finally, it needs to find the convert-ly script from the current LilyPond development build.

By default, executing makelsr.pl performs the following actions.

• Download documentation snippets from the LilyPond Wiki.
• Delete all snippet and snippet list files in directory Documentation/snippets/ (but not in Documentation/snippets/new/).
• Convert the snippets’ documentation parts from MediaWiki syntax to Texinfo with the pandoc program, run the script convert-ly to update their LilyPond code parts to current syntax, and store them in Documentation/snippets/.
• Create snippet list files (with extension .snippet-list) that group snippets by Wiki categories. These files are used to structure LilyPond’s ‘Snippets’ manual.
• Convert all snippet files in Documentation/snippets/new/ with convert-ly and output them to Documentation/snippets/, possibly overwriting existing files.

This flow of actions can be adjusted; say ‘scripts/auxiliar/makelsr.pl --help’ to get a detailed description of the provided command-line options and used environment variables.