Docs: discourage implicit relative in lilypond[verbatim]; issue 4371

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index cdd069ed5dc22d3fa5d9b59cb954f4eacad63798..f9718249a8be01eb3bcd627f093ab0e80d942f41 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -410,14 +410,7 @@ or
 @@lilypond[verbatim,quote,relative=2]
 @end example
 
-If using any combination of @code{\header@{@}}, @code{\score@{@}} or
-@code{\layout@{@}} in your example, then you must omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction.
-
-If using @code{\book@{@}} in your example then you must also omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction.  However, you must also
+If using @code{\book@{@}} in your example then you must also
 include the @code{papersize=X} variable, where @code{X} is a defined
 paper size from within @file{scm/paper.scm}.  This is to avoid the
 default @code{a4} paper size being used and leaving too much unnecessary

diff --git a/Documentation/learning/common-notation.itely b/Documentation/learning/common-notation.itely
index 9dcca07a431eefe47b38b8ecb300ebb4e5340535..c75409e71736cb6f36155f05b04ab66799fb2e0b 100644 (file)
--- a/Documentation/learning/common-notation.itely
+++ b/Documentation/learning/common-notation.itely
@@ -1419,13 +1419,13 @@ above the music.  More information on titling can be found in
 @cindex pitches, absolute values
 @cindex absolute note names
 
-So far we have always used @code{\relative} to define pitches.
+So far we have used @code{\relative} to define pitches.
 This is usually the fastest way to enter most music.  Without
 @code{\relative}, pitches are interpreted in absolute mode.
 
 In this mode, LilyPond treats all pitches as absolute values.  A
-@code{c'} will always mean middle C, a @code{b} will always mean
-the note one step below middle C, and a @code{g,} will always mean
+@code{c'} will always mean middle@tie{}C, a @code{b} will always mean
+the note one step below middle@tie{}C, and a @code{g,} will always mean
 the note on the bottom staff of the bass clef.
 
 @lilypond[verbatim,quote]

diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely
index c63c9baa63e19a11ca95285245d6c180d61d1279..d9fcb03d65114d9d390736bce9ce4dd9193b7a28 100644 (file)
--- a/Documentation/learning/tutorial.itely
+++ b/Documentation/learning/tutorial.itely
@@ -214,6 +214,16 @@ Music Glossary: @rglos{pitch}, @rglos{interval},
 @rglos{scale}, @rglos{middle C}, @rglos{octave},
 @rglos{accidental}.
 
+LilyPond uses lower-case letters for pitches.  The letters
+@code{c} through@tie{}@code{b} denote pitches in the
+@q{small octave} below @notation{middle C}.  Added @code{'}
+or@tie{}@code{,} suffixes indicate higher or lower octaves.
+Here is a scale starting on @notation{middle C}, and an arpeggio:
+
+@lilypond[verbatim,quote]
+{ c' d' e' f' g' a' b' c'' g c' e' g' c'' e'' g'' c''' }
+@end lilypond
+
 The easiest way to enter notes is by using @code{\relative} mode.
 In this mode, the octave is chosen automatically by assuming the
 following note is always to be placed closest to the previous
@@ -694,17 +704,6 @@ form of @code{@bs{}relative} with an explicit starting pitch
 @}
 @end example
 
-Why omit the braces?  Most examples in this manual can be inserted
-into the middle of a longer piece of music.  For these examples,
-it does not make sense to add
-@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} -- you should not
-place a @code{\relative} inside another @code{\relative}!  If we
-included @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} around
-every example, you would not be able to copy a small documentation
-example and paste it inside a longer piece of your own.  Most
-people want to add material to an existing piece, so we format the
-manual this way.
-
 Also, remember that every LilyPond file should have a
 @code{\version} statement.  Because the examples in the manuals
 are snippets, not files, the @code{\version} statement is omitted.

diff --git a/Documentation/nl/learning/common-notation.itely b/Documentation/nl/learning/common-notation.itely
index 23be70165df1ebb65f4e995ad6d7112825147e41..bb586e1231071bd41a05a71de6fb2db55fd4293a 100644 (file)
--- a/Documentation/nl/learning/common-notation.itely
+++ b/Documentation/nl/learning/common-notation.itely
@@ -634,7 +634,8 @@ In LilyPond-invoerbestanden wordt muziek gerepresenteerd
 door @emph{muziekuitdrukkingen}.  Een enkele noot is een
 muziekuitdrukking:
 
-@lilypond[verbatim,quote,relative=2] a4
+@lilypond[verbatim,quote,fragment]
+a'4
 @end lilypond
 
 Een noot tussen accolades zetten maakt er een