5.5.1 Books

The five main parts of the documentation are the Learning Manual, the Notation Reference, the Application Usage, the Music Glossary, and the Internals Reference.

• Learning Manual

  The LM is written in a tutorial style which introduces the most important concepts, structure and syntax of the elements of a LilyPond score in a carefully graded sequence of steps. Explanations of all musical concepts used in the manual can be found in the Music Glossary, and readers are assumed to have no prior knowledge of LilyPond. The objective is to take readers to a level where the Notation Reference can be understood and employed to both adapt the templates in the Appendix to their needs and to begin to construct their own scores. Commonly used tweaks are introduced and explained. Examples are provided throughout which, while being focused on the topic being introduced, are long enough to seem real in order to retain the readers’ interest. Each example builds on the previous material, and comments are used liberally. Every new aspect is thoroughly explained before it is used.

  Users are encouraged to read the complete Learning Manual from start to finish.

• Notation Reference

  This is a (hopefully complete) description of LilyPond’s input notation. Some material from here may be duplicated in the Learning Manual (for teaching), but consider the NR to be the ‘definitive’ description of each notation element, with the LM being an ‘extra’. The goal is not to provide a step-by-step learning environment – do not avoid using notation that has not be introduced previously in the NR (for example, use \break if appropriate). The NR is written in formal technical writing style.

  Avoid duplication. Although users are not expected to read this manual from start to finish, they should be familiar with the material in the Learning Manual (particularly “Fundamental Concepts”), so do not repeat that material in each section of this book. Also watch out for common constructs, like ‘^’, ‘-’, and ‘_’ for directions – those are explained in NR chapter 5. In NR chapter 1, for example, you can use a reference and write:

  Dynamics may be manually placed above or below the staff, see
  @ref{Direction and placement}.
  

  Most tweaks should be added to the LSR and not placed directly in the .itely file. In some cases, tweaks may be placed in the main text, but ask about this first.

  Finally, you should assume that users know what the notation means; explaining musical concepts happens in the Music Glossary.

• Application Usage

  This manual gives information about calling and using the lilypond program itself and other tools related to it (in particular convert-ly and lilypond-book), issues related to differences in the used operating system, some pointers to external programs, etc. This manual is written in formal technical writing style.

  Users are not expected to read this manual from start to finish.

• Music Glossary

  Information about the music notation itself. Explanations and translations about notation terms go here.

  Users are not expected to read this manual from start to finish.

• Internals Reference

  This manual is automatically generated from documentation strings embedded in the source code. It provides an in-depth reference to almost all low-level details of LilyPond.

  Users are not expected to read this manual at all. It should rather be used like a dictionary to look up, say, all properties and sub-properties of a slur. The writing style is extremely terse and technical (sometimes too terse, admittedly).