[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Sectioning commands ]		[  Up : Texinfo introduction and usage policy ]	[ Text formatting > ]

5.4.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 papersizes 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,quote,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 #` 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
    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.

---

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Sectioning commands ]		[  Up : Texinfo introduction and usage policy ]	[ Text formatting > ]

<< Back to Documentation Index

LilyPond — Contributor’s Guide v2.19.6 (development-branch).