X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fworking.itely;h=8a416f7ad7fea23364fda4807ceac99cece5fdf3;hb=199e97714242780f3694a2e501c917c54ad64a53;hp=1d1841f56376d9e172b821ce9b674d75e270af05;hpb=359de2c403a63efb47e55b18cff59d5f31e9ba44;p=lilypond.git diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely index 1d1841f563..8a416f7ad7 100644 --- a/Documentation/user/working.itely +++ b/Documentation/user/working.itely @@ -1,8 +1,16 @@ @c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + @node Working on LilyPond projects @chapter Working on LilyPond projects -This section explains a how to solve or avoid certain common +This section explains how to solve or avoid certain common problems. If you have programming experience, many of these tips may seem obvious, but it is still advisable to read this chapter. @@ -14,6 +22,7 @@ this chapter. * Style sheets:: * Updating old files:: * Troubleshooting (taking it all apart):: +* Minimal examples:: @end menu @@ -61,17 +70,17 @@ problems: @itemize @bullet @item @strong{Include @code{\version} numbers in every file}. Note that all -templates contain a @code{\version "2.8.0"} string. We +templates contain a @code{\version "2.11.15"} string. We highly recommend that you always include the @code{\version}, no matter how small your file is. Speaking from personal experience, it's quite frustrating to try to remember which version of LilyPond you were using a few years ago. @code{convert-ly} requires you to declare which version of LilyPond you used. -@item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If -you +@item @strong{Include checks}: @ref{Bar check}, @ref{Octave check}, and +@ref{Barnumber check}. If you include checks every so often, then if you make a mistake, you can pinpoint -it quicker. How often is ``every so often''? It depends on the complexity +it quicker. How often is @q{every so often}? It depends on the complexity of the music. For very simple music, perhaps just once or twice. For very complex music, perhaps every bar. @@ -79,12 +88,12 @@ very complex music, perhaps every bar. either in the music itself or in the output you desire, it's often good to write only one bar per line. Saving screen space by cramming eight bars per line just isn't -worth it if you have to `debug' your files. +worth it if you have to @q{debug} your files. @item @strong{Comment your files}. Use either bar numbers (every so often) or -references to musical themes (``second theme in violins,'' ``fourth -variation'', etc). You may not need comments when you're writing the piece +references to musical themes (@q{second theme in violins,} @q{fourth +variation,} etc.). You may not need comments when you're writing the piece for the first time, but if you want to go back to change something two or three years later, or if you pass the source over to a friend, it will be much more @@ -101,7 +110,7 @@ phrase (instead of just @code{c d e}) you can save yourself some problems if you rearrange your music later. @item @strong{Separate tweaks} from music definitions. See -@ref{Saving typing with identifiers and functions} and +@ref{Saving typing with identifiers and functions}, and @ref{Style sheets}. @end itemize @@ -181,6 +190,9 @@ g4\fthenp c'8. e16 @node Saving typing with identifiers and functions @section Saving typing with identifiers and functions +@cindex variables +@cindex identifiers + By this point, you've seen this kind of thing: @lilypond[quote,verbatim,ragged-right] @@ -283,13 +295,13 @@ instead of making changes throughout every @code{.ly} file. @section Style sheets The output that LilyPond produces can be heavily modified; see -@ref{Tweaking output} for details. But what if you have many +@ref{Tweaking output}, for details. But what if you have many files that you want to apply your tweaks to? Or what if you simply want to separate your tweaks from the actual music? This is quite easy to do. Let's look at an example. Don't worry if you don't understand -the parts with all the #(). This is explained in +the parts with all the @code{#()}. This is explained in @ref{Advanced tweaks with Scheme}. @lilypond[quote,verbatim,ragged-right] @@ -298,7 +310,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $markp } #}) @@ -317,7 +329,7 @@ definitions. They produce the output we desire, but we might want to use them in another piece. We could simply copy-and-paste them at the top of every file, but that's an annoyance. It also leaves those definitions in our music files, and I personally find all -the #() somewhat ugly. Let's hide them in another file: +the @code{#()} somewhat ugly. Let's hide them in another file: @example %%% save this to a file called "definitions.ly" @@ -326,7 +338,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #@{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup @{ \bold $markp @} #@}) @end example @@ -354,7 +366,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $markp } #}) @@ -370,8 +382,8 @@ tempoMark = #(define-music-function (parser location markp) (string?) That looks better, but let's make a few changes. The glissando is hard to see, so let's make it thicker and closer to the noteheads. Let's put the metronome marking above the clef, instead of over the first -note. And finally, my composition professor hates "C" time signatures, -so we'd better make that "4/4" instead. +note. And finally, my composition professor hates @q{C} time signatures, +so we'd better make that @q{4/4} instead. Don't change @file{music.ly}, though. Replace our @file{definitions.ly} with this: @@ -383,7 +395,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #@{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup @{ \bold $markp @} #@}) @@ -408,7 +420,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $markp } #}) @@ -436,7 +448,7 @@ tempoMark = #(define-music-function (parser location markp) (string?) @end lilypond That looks nicer! But now suppose that I want to publish this -piece. My composition professor doesn't like "C" time +piece. My composition professor doesn't like @q{C} time signatures, but I'm somewhat fond of them. Let's copy the current @file{definitions.ly} to @file{web-publish.ly} and modify that. Since this music is aimed at producing a pdf which @@ -450,7 +462,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #@{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup @{ \bold $markp @} #@}) @@ -475,7 +487,7 @@ mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) tempoMark = #(define-music-function (parser location markp) (string?) #{ \once \override Score . RehearsalMark #'self-alignment-X = #left - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $markp } #}) @@ -520,12 +532,12 @@ prefers. The top of @file{music.ly} would then look like this: This approach can be useful even if you are only producing one set of parts. I use half a dozen different -``style sheet'' files for my projects. I begin every music +@q{style sheet} files for my projects. I begin every music file with @code{\include "../global.ly"}, which contains @example %%% global.ly -\version "2.8.0" +\version "2.11.15" #(ly:set-option 'point-and-click #f) \include "../init/init-defs.ly" \include "../init/init-layout.ly" @@ -546,7 +558,7 @@ LilyPond comes with a file that makes this updating easier: @code{convert-ly}. For details about how to run this program, see @ref{Updating files with convert-ly}. -Unforunately, @code{convert-ly} cannot handle all input changes. It +Unfortunately, @code{convert-ly} cannot handle all input changes. It takes care of simple search-and-replace changes (such as @code{raggedright} becoming @code{ragged-right}), but some changes are too complicated. The syntax changes that @code{convert-ly} cannot handle @@ -554,9 +566,9 @@ are listed in @ref{Updating files with convert-ly}. For example, in LilyPond 2.4 and earlier, accents and non-English letters were entered using LaTeX -- for example, -"@code{No\"el}" (this would print the French word for -`Christmas'). In LilyPond 2.6 and above, the special -"@code{ë}" must be entered directly into the LilyPond file as an +@samp{No\"el} (this would print the French word for +@q{Christmas}). In LilyPond 2.6 and above, the special +@samp{ë} must be entered directly into the LilyPond file as an UTF-8 character. @code{convert-ly} cannot change all the LaTeX special characters into UTF-8 characters; you must manually update your old LilyPond files. @@ -613,4 +625,46 @@ bass = \relative c' @{ Now start slowly uncommenting more and more of the @code{bass} part until you find the problem line. +Another very useful debugging technique is constructing +@ref{Minimal examples}. + + +@node Minimal examples +@section Minimal examples + +A minimal example is an example which is as small as possible. These +examples are much easier to understand than long examples. Minimal +examples are used for + +@itemize +@item Bug reports +@item Sending a help request to mailists +@item Adding an example to the @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond +Snippet Repository} +@end itemize + +To construct an example which is as small as possible, the rule is +quite simple: remove anything which is not necessary. When trying to +remove unnecessary parts of a file, it is a very good idea to comment +out lines instead of deleting them. That way, if you discover that you +actually @emph{do} need some lines, you can uncomment them, instead of +typing them in from scratch. + +There are two exceptions to the @qq{as small as possible} rule: + +@itemize +@item Include the @code{\version} number. +@item If possible, use @code{\paper@{ ragged-right=##t @}} at the +top of your example. +@end itemize + +The whole point of a minimal example is to make it easy to read: + +@itemize +@item Avoid using complicated notes, keys, or time signatures, unless you +wish to demonstrate something is about the behavior of those items. +@item Do not use @code{\override} commands unless that is the point of the +example. +@end itemize +