Skip to content

Basic Usage

Jump to bottom
Urs Liska edited this page Jul 12, 2017 · 5 revisions

In order to use an openLilyLib package it first has to be loaded, which we'll see in a minute. Any package defines an arbitrary number of new commands that are available to the LilyPond document, or it executes custom code that already affects the appearance or behaviour upon loading. A package can provide modules that can be loaded independently, and it can be configurable through options. The details of modules, behavior and options should be documented by each package itself.

Loading oll-core

The first step is loading openLilyLib “as such” with

\include "oll-core/package.ily"

Assuming the basic installation procedures on the introductory page have been successfully completed this should compile (without visible result) and load the openLilyLib infrastructure. Loading oll-core makes many useful tools available, so it can even make sense to load it as the only openLilyLib package.

Loading Packages

The basic command to load an openLilyLib package is

\loadPackage <package-name>

<package-name> corresponds to the repository name and equally to the directory in which the package is saved. Therefore it is essential to keep the folder names when cloning or unzipping a package into the openLilyLib installation directory. However, it is used in case-insensitive manner, so “decorative” capitalizations like scholarLY or anaLYsis are possible.

Loading Packages With Options

It is possible to configure a package upon loading by passing options to the \loadPackage command:

\loadPackage \with {
  an-option = value
  another-opt = #'(2 . 4)
}
analysis

The accepted option names are defined by each package, and unknown options are discarded, with a warning issued. Note that options are not typed (yet), so the input document is responsible for setting the options to meaningful values.

Loading Packages With Modules

If a package exports modules these are by default not loaded implicitly together with the package. However, with the special option modules one or more (top-level) modules can be specified in symbol-list dot notation:

\loadPackage \with {
  an-options = #()
  modules = arrows.frames
}
analysis

\loadPackage \with {
  modules = editorial-functions
}  
scholarLY

In the first example two modules, arrows and frames are loaded together with the package analysis, the second shows how a single module is loaded. Module names should be used in their proper case, and if a module is not present (e.g. mistyped) it is ignored with a warning. Note that while modules can be configured with options too, this is not supported by this syntax. For better control modules have to be loaded separately:

Loading Modules

Loading a Single Module

The basic command to load a module is \loadModule [options] module-path. module-path is a symbol-list whose first element is the package name and the remaining elements specify the “path” to the (sub-)module. Currently snippets is the only package with actual submodules.

% load the “editorial-functions” module from the “scholarly” package
\loadModule scholarly.editorial-functions

% load "notation-snippets.shaping-bezier-curves" from the "snippets" repository
\loadModule snippets.notation-snippets.shaping-bezier-curves

\loadModule implicitly loads the package if it hasn't been loaded yet.

As with packages module options can be passed, and unsupported options will be discarded with a warning:

% load the “frames” module from the “analysis” package
\loadModule \with {
  padding = 1
  border-radius = 1.5
  color = #'(0.3 0.6 0)
}
analysis.frames

Loading Multiple Modules

\loadModules <package> <modules> loads multiple modules from one package. As with \loadModule the package may implicitly be loaded along the way, and as with the modules option of \loadPackage module options can not be passed with this invocation.

<modules> has to be a list whose elements are either Scheme symbols or symbol-lists. Any symbol will be interpreted as a top-level module while symbol-lists refer to submodules, so the following “flat” symbol-list

\loadModules analysis arrows.frames
% or
\loadModules analysis #'(arrows frames)

loads the two modules arrows and frames from the analysis package, while

\loadModules scholarly
#'(editorial-functions
   (export latex)
   (export html)
   annotate)

would load the editorial-functions and annotate top-level modules and the export/latex and export/html submodules (note that these don't exist yet).

Conclusion

There are several commands to load packages and modules, and they may seem conflicting. However, they provide different trade-offs between loading multiple items at once and providing fine-grained control, so there may be different “best practices” for different use cases. If in doubt the basic order

  • include oll-core
  • use \loadPackage (with or without options) for each package
  • use \loadModule (with or without options) for each module in that package

may be tediously verbose but is definitely “correct”.

Package and Module Options

Note that package and modules options can not only be set upon loading but also individually. Many can even be changed within the music. This is explained in detail on option handling.

Clone this wiki locally