LilyPond Contributor's Guide: 5.3.4 LilyPond formatting

### 5.3.4 LilyPond formatting

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

  >     @lilypond[verbatim,quote,relative=1]

  or

  >     @lilypond[verbatim,quote,relative=2]

  If using any combination of `\header{}`, `\score{}` or `\layout{}` in your example, then you must omit the `relative` variable and either use absolute entry mode or an explicit `\relative{}` construction.

  If using `\book{}` in your example then you must also omit the `relative` variable and either use absolute entry mode or an explicit `\relative{}` construction. However, you must also include the `papersize=X` variable, where `X` is a defined paper size from within ‘`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`s are `a5`, `a6` or `a8landscape`.

  `a8landscape` works best for a single measure with a single title and/or 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, RH and LH 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.

- Please avoid using extra spacing either after or within the `@lilypond` parameters.

  >     not:          @lilypond [verbatim, quote, relative=1]
  >     but instead:  @lilypond[verbatim,quote,relative=1]

- Inspirational headwords are produced with:

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

- LSR snippets are linked with:

  >     @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
  >     {filename.ly}

- Use two spaces for indentation in lilypond examples (no tabs).
- All engravers should have double-quotes around them:

  >     \consists "Spans_arpeggio_engraver"

  LilyPond does not strictly require this, but it is a useful convention to follow.

- All context or layout object strings should be prefaced with `#`. Again, LilyPond does not strictly require this, but it is helpful to get users accustomed to this scheme construct, i.e. `\set Staff.instrumentName = #"cello"`
- Try to avoid using `#'` or `#`` within when describing context or layout properties outside of an `@example` or `@lilypond`, unless the description explicitly requires it.

  i.e. “...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, omit bar checks. If you must put more than one bar per line (not recommended), then include bar checks.
- 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"

  excepted in Templates, where ‘doctitle’ may be omitted.

- Avoid long stretches of input code. Nobody is going to read them in print. Create small examples. However, this does not mean it has 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, always use { } marks even if they are not technically required; i.e.

  >     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 { } marks; i.e.

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

- Use { } marks for additional `\markup` format commands; i.e.

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

- Remove any space around `<` `>` marks; i.e.

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

- Beam, slur and tie marks should begin immediately after the first note with beam and phrase marks ending immediately after the last.

  >     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 = 160\mm - 2.0 * 0.4\in
  >       ragged-right = ##t
  >       force-assignment = #""
  >       line-width = #(- line-width (* mm  3.000000))
  >     }

  >     \layout {
  >     }

  You may not change any of these values. If you are making an example demonstrating special `\paper{}` values, contact the Documentation Editor.

#### LilyPond — Contributor’s Guide