@menu
* Suggestions for writing LilyPond files::
+* Updating old files::
* Troubleshooting (taking it all apart)::
* Saving typing with identifiers::
+* Style sheets::
@end menu
@end itemize
+@node Updating old files
+@section Updating old files
+
+The LilyPond input syntax occasionally changes. As LilyPond itself
+improves, the syntax (input language) is modified accordingly. Sometimes
+the changes are made to make the input easier to read and write, and
+sometimes the changes are made to accomodate new features of LilyPond.
+
+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
+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
+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}" (Christmas). In LilyPond 2.6 and above, the special
+"@code{ë}" 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.
+
+
@node Troubleshooting (taking it all apart)
@section Troubleshooting (taking it all apart)
}
@end lilypond
+Using identifiers is also a good way to reduce work if the
+LilyPond input syntax changes (see @ref{Updating old files}). If
+you have a single definition (such as @code{\dolce}) for all your
+files (see @ref{Style sheets}), then if the syntax changes, you
+only need to update your single @code{\dolce} definition,
+instead of making changes throughout every @code{.ly} file.
+
+
+@node Style sheets
+@section Style sheets
+
+The output that LilyPond produces can be heavily modified; see
+@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
+@ref{Advanced tweaks with scheme}.
+
+@lilypond[quote,verbatim,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+There are some problems with overlapping output; we'll fix those using
+the techiques in @ref{Fixing overlapping notation}. But let's also
+do something about the @code{mpdolce} and @code{tempoMark}
+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:
+
+@example
+%%% save this to a file called "definitions.ly"
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+@end example
+
+Now let's modify our music (let's save this file as @file{"music.ly"}).
+
+@c We have to do this awkward example/lilypond-non-verbatim
+@c because we can't do the \include stuff in the manual.
+
+@example
+\include "definitions.ly"
+
+\relative c'' @{
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+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.
+
+Don't change @file{music.ly}, though. Replace our @file{definitions.ly}
+with this:
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ \override TimeSignature #'style = #'numbered
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Staff
+ \override TimeSignature #'style = #'numbered
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+That looks nicer! But now suppose that I want to publish this
+piece. My composition professor doesn't like "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 produce a pdf which
+will be displayed on the screen, we'll also increase the
+overall size of the output.
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup @{ \bold $markp @}
+#@})
+
+#(set-global-staff-size 23)
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \mark \markup { \bold $markp }
+#})
+
+#(set-global-staff-size 23)
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+Now in our music, I can either simply replace
+@code{\include "definitions.ly"} with
+@code{\include "web-publish.ly"}. Of course, we could make this
+even more convenient. We could make a @file{definitions.ly} file which only
+contains the definitions of @code{mpdolce} and @code{tempoMark}, a
+@file{web-publish.ly} file which only contains the @code{\layout}
+section listed above, and a @file{university.ly} file which
+contains the tweaks to produce the output that my professor
+prefers. The top of @file{music.ly} would then look like this:
+
+@example
+\include "definitions.ly"
+
+%%% Only uncomment one of these two lines!
+\include "web-publish.ly"
+%\include "university.ly"
+@end example
+
+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
+file with @code{\include "../global.ly"}, which contains
+
+@example
+%%% global.ly
+\version "2.8.0"
+#(ly:set-option 'point-and-click #f)
+\include "../init/init-defs.ly"
+\include "../init/init-layout.ly"
+\include "../init/init-headers.ly"
+\include "../init/init-paper.ly"
+@end example