5.4.5 LilyPond formatting

Here are some guidelines how to format LilyPond code in @lilypond … @end lilypond blocks.

• Most LilyPond examples throughout the documentation can be produced with:

  @lilypond[verbatim,quote]
  

  If you need \book{} in your example then you must also include the papersize=X variable, where X is a paper size as defined in file scm/paper.scm. This is to avoid the default a4 paper size being used and leaving too much unnecessary whitespace and potentially awkward page breaks in the PDFs.

  The preferred papersize values are a5, a6, or a8landscape.

  a8landscape works best for a single measure with a single title and/or a single tagline:

  @lilypond[papersize=a8landscape,verbatim]
  \book {
    \header {
      title = "A scale in LilyPond"
    }
    \relative {
      c d e f
    }
  }
  @end lilypond
  

  and can also be used to easily show features that require page breaks (i.e., page numbers) without taking large amounts of space within the documentation. Do not use the quote option with this paper size.

  a5 or a6 paper sizes are best used for examples that have more than two measures of music or require multiple staves (i.e., to illustrate cross-staff features, right-hand and left-hand parts, etc.) and where \book{} constructions are required or where a8landscape produces an example that is too cramped. Depending on the example the quote option may need to be omitted.

  In rare cases, other options may be used (or omitted), but ask first.

• For consistency with the existing documentation source code, please avoid using extra spacing either after or within the @lilypond parameters.

  not:          @lilypond [verbatim, quote, fragment]
  but instead:  @lilypond[verbatim,quote,fragment]
  

• Inspirational headwords are produced with:

  @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
  {topic-headword.ly}
  

• LSR snippets are linked with:

  @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
  {name.ly}
  

• Use two spaces for indentation in LilyPond examples (no tabs).
• Try to avoid using #' or #` when describing context or layout properties outside of an @example or @lilypond, unless the description explicitly requires it.

  Example: “…setting the transparent property leaves the object where it is, but makes it invisible.”

• If possible, only write one bar per line.
• If you only have one bar per line, you might omit bar checks. If you must put more than one bar per line (not recommended), then do include bar checks.
• \override tweaks should, if possible, also occur on their own line.

  not:          \override TextScript.padding = #3 c1^"hi"
  but instead:  \override TextScript.padding = #3
                c1^"hi"
  

• Avoid long stretches of input code. Nobody is going to read them in print. Create small examples. However, this does not mean it has to be minimal.
• Specify durations for at least the first note of every bar.
• If possible, end with a complete bar.
• Comments should go on their own line, and be placed before the line(s) to which they refer.
• For clarity, use ‘{’ and ‘}’ even if they are not technically required.

  not:
  
  \context Voice \repeat unfold 2 \relative c' {
    c2 d
  }
  
  but instead:
  
  \context Voice {
    \repeat unfold 2 {
      \relative c' {
        c2 d
      }
    }
  }
  

• Add a space around ‘{’ and ‘}’.

  not:          \chordmode{c e g}
  but instead:  \chordmode { c e g }
  

• Use ‘{’ and ‘}’ for additional \markup format commands.

  not:          c^\markup \tiny\sharp
  but instead:  c^\markup { \tiny \sharp }
  

• Remove any space around ‘<’ and ‘>’ (except for situations like <c e g-> >, which would cause a syntax error otherwise).

  not:           < c e g > 4
  but instead:   <c e g>4
  

• Beam and slur marks should begin immediately after the first note (i.e., without a space in between), and end immediately after the last. Ties should also be attached without a space before the tilde sign.

  a8\( ais16[ b cis( d] b) cis4~ b' cis,\)
  

• If you want to work on an example outside of the manual (for easier/faster processing), use this header.

  \paper {
    indent = 0\mm
    line-width = 135.68\mm
  }
  
  \layout {}
  

  This is the default line width and indentation value used by lilypond-book (which converts the LilyPond code to PDF or PNG images) for @lilypond blocks with the quote option and no other overrides. Without the quote option, the line width is 156mm.