Hi folks, When writing examples for the NR, make sure to include any "enclosing context" in the user-visible part of each example.
For example, notation example 6 in the new NR 5.3.6 "\tweak and \single" section ... https://lilypond.org/doc/v2.25/Documentation/notation/tweak-and-single ... appears on-screen to users as a lone chord ... < \single \easyHeadsOn c' g' >2 ... with corresponding output that appears to be in the wrong octave: The on-screen input suggests a perfect fifth in the octave above middle-C, but the on-screen output shows the perfect fifth an octave higher than this. To any user who's actually paying, this appears to be a bug. What's actually going on here is that "enclosing context" in the form of a \relative block is missing from the *user-visible* part of the example. If a user happens to be reading the docs online, then it is possible to click on the example to reveal its source, which makes it easy to see the problem: %%% BEGIN EXAMPLE SOURCE %%% %% Generated by lilypond-book %% Options: [exampleindent=10.16\mm,fragment,indent=0\mm,line-width=160\mm,paper-height=845.047\pt,paper-width=597.508\pt,papersize='(cons (* 597.508 pt) (* 845.047 pt)),quote,relative=1] \include "lilypond-book-preamble.ly" % **************************************************************** % Start cut-&-pastable-section % **************************************************************** #(ly:set-option 'eps-box-padding 3.000000) \paper { #(set-paper-size '(cons (* 597.508 pt) (* 845.047 pt))) indent = 0\mm line-width = 160\mm % offset the left padding, also add 1mm as lilypond creates cropped % images with a little space on the right line-width = #(- line-width (* mm 3.000000) (* mm 1)) line-width = 160\mm - 2.0 * 10.16\mm % offset the left padding, also add 1mm as lilypond creates cropped % images with a little space on the right line-width = #(- line-width (* mm 3.000000) (* mm 1)) } \layout { } \relative c' { % **************************************************************** % ly snippet contents follows: % **************************************************************** \sourcefileline 2425 < \single \easyHeadsOn c' g' >2 % **************************************************************** % end ly snippet % **************************************************************** } %%% END EXAMPLE SOURCE %%% Within the source, the "snippet contents" block looks like this ... % **************************************************************** % ly snippet contents follows: % **************************************************************** \sourcefileline 2425 < \single \easyHeadsOn c' g' >2 % **************************************************************** % end ly snippet % **************************************************************** ... but should include \relative { } and look like this ... % **************************************************************** % ly snippet contents follows: % **************************************************************** \sourcefileline 2425 \relative c' { < \single \easyHeadsOn c' g' >2 } % **************************************************************** % end ly snippet % **************************************************************** ... instead. Please note that the idea that users should just click on the example to discover "enclosing context" (if any) to each example is not ok. Each example should show what it purports to show. And users reading the docs as PDF have no ability to click on the output of any example. The most common form of this problem is the stranding of a \relative expression, as shown above. But it is also sometimes the case that the braces of a sequential music expression are omitted. Notation example 2 of the 2.25 version of NR 5.4.6 "Line spanners" ... https://lilypond.org/doc/v2.25/Documentation/notation/line-spanners ... shows four lines of code ... \override Glissando.breakable = ##t \override Glissando.bound-details.right-broken.Y = -3 c''1 \glissando \break f''1 .... that will explode if users try to evaluate them. This is not a valid LilyPond expression. What's missing are the surrounding braces of a sequential music expression, again hidden behind a hyperlink. The example should read ... { \override Glissando.breakable = ##t \override Glissando.bound-details.right-broken.Y = -3 c''1 \glissando \break f''1 } ... instead. Reading through past pages in the changelog, it seems like this problem was much, much more common in the past. The modern versions of the docs are, in general, very good about avoiding this problem. But please continue to keep an eye out for it, because these examples appear to be a result of a gap in the documentation process / system: all such examples do, in fact, compile and build correctly for the website, but they read as incorrect (or un-compilable) to readers of the docs who are carefully following along. -- Trevor Bača www.trevorbaca.com soundcloud.com/trevorbaca
