+
+@node Relative octave entry
+@unnumberedsubsubsec Relative octaves entry
+
+@cindex Relative
+@cindex Relative octave specification
+@funindex \relative
+
+The absolute mode requires a lot of octave specifications, which
+not only becomes tedious but also easily leads to errors.
+Therefore, it is usually more convenient to let notes be entered
+relative to the previous note. This is done with the relative
+mode.
+
+@example
+\relative @var{startpitch} @var{musicexpr}
+@end example
+
+In relative mode, each note is assumed to be as close to the
+previous note as possible. This means that the octave of notes
+that appear in @var{musicexpr} are calculated as follows:
+
+@itemize
+@item
+The pitch of the first note is relative to @code{\relative
+@var{startpitch} }.
+
+@item
+If no octave changing marks are used, the basic interval between a
+note and the one that precedes it is always taken to be a fourth
+or less.
+
+@item
+This distance is determined without regarding alterations or the
+actual sounding pitches; a @code{fisis} following a @code{ceses}
+will be put above the @code{ceses}. In other words, a
+doubly-augmented fourth is considered a smaller interval than a
+diminished fifth, even though the doubly-augmented fourth spans
+seven semitones while the diminished fifth only spans six
+semitones.
+
+@item
+The octave changing marks @code{'} and @code{,} can be added to
+raise or lower the pitch by an extra octave from the basic
+interval.
+
+@item
+Multiple octave changing marks can be used. @code{''} will raise
+the pitch by two octaves.
+
+@end itemize
+
+Here is the relative mode shown in action:
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+\relative c'' {
+ b c d c b c bes a
+}
+@end lilypond
+
+Octave changing marks are used for intervals greater than a
+fourth:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c'' {
+ c g c f, c' a, e''
+}
+@end lilypond
+
+A note sequence without a single octave mark can nevertheless span
+large intervals:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c {
+ c f b e a d g
+}
+@end lilypond
+
+If the preceding item is a chord, the first note of the chord is
+used as the reference point for the octave placement of a
+following note or chord:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' {
+ c <c e g>
+ <c' e g>
+ <c, e' g> c
+}
+@end lilypond
+
+The @var{startpitch} (after @code{\relative}) is a note name in
+absolute mode. In principle it can be any note name, but common
+practice is to use @code{c} in various octave positions.
+
+When octaves are specified as above by adding @code{'} and
+@code{,} to pitch names, it is easy to accidentally put a pitch in
+the wrong octave. The relative octave mode prevents these errors
+since most of the time it is not necessary to indicate any octaves
+at all. Furthermore, in absolute mode, a single mistake may be
+difficult to spot; in relative mode, a single error puts the rest
+of the piece off by one octave.
+
+@seealso
+
+Snippets: @lsrdir{pitch}
+
+
+@refbugs
+
+The relative conversion will not affect @code{\transpose},
+@code{\chordmode} or @code{\relative} sections in its argument.
+To use relative within transposed music, an additional
+@code{\relative} must be placed inside @code{\transpose}.
+
+@c DEPRECATED
+If no @var{startpitch} is specified for @code{\relative}, then
+@code{c'} is assumed. However, this is a deprecated option and
+may disappear in future versions, so its use is discouraged.
+
+