From c14fbcd481f9f637b2cfe8318ff818c01892214a Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Fri, 21 Sep 2007 15:44:39 -0700 Subject: [PATCH] More Learning manual rearrangement. --- Documentation/user/changing-defaults.itely | 4 +- Documentation/user/fundamental.itely | 300 ++++++++++++++++++ Documentation/user/lilypond-learning.tely | 10 +- Documentation/user/lilypond.tely | 4 - Documentation/user/non-music.itely | 36 --- Documentation/user/piano.itely | 2 +- .../user/programming-interface.itely | 2 +- Documentation/user/putting.itely | 254 --------------- Documentation/user/vocal.itely | 2 +- Documentation/user/working.itely | 2 +- 10 files changed, 314 insertions(+), 302 deletions(-) create mode 100644 Documentation/user/fundamental.itely diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 3e07a465b1..cef3f0429b 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -63,7 +63,7 @@ Internally, LilyPond uses Scheme (a LISP dialect) to provide infrastructure. Overriding layout decisions in effect accesses the program internals, which requires Scheme input. Scheme elements are introduced in a @code{.ly} file with the hash mark -@code{#}.@footnote{@ref{Scheme tutorial}, contains a short tutorial +@code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.} @@ -1438,7 +1438,7 @@ Then the output at the start of this subsection can be entered as @subsection Aligning contexts New contexts may be aligned above or below exisiting contexts. This -could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and +could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and in ossia, @cindex ossia diff --git a/Documentation/user/fundamental.itely b/Documentation/user/fundamental.itely new file mode 100644 index 0000000000..fa867e96b7 --- /dev/null +++ b/Documentation/user/fundamental.itely @@ -0,0 +1,300 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@node Fundamental concepts +@chapter Fundamental concepts + +@menu +* File structure (introduction):: +* How LilyPond files work:: +* Score is a single musical expression:: +@end menu + + +@node File structure (introduction) +@section File structure (introduction) + +A basic example of a lilypond input file is + +@example +\version "2.11.23" +\score @{ + @{ @} % this is a single music expression; + % all the music goes in here. + \header @{ @} + \layout @{ @} + \midi @{ @} +@} +@end example + +@noindent +There are many variations of this basic pattern, but this +example serves as a useful starting place. + +The major part of this manual is concerned with entering various +forms of music in LilyPond. However, many music expressions are not +valid input on their own, for example, a @code{.ly} file containing +only a note +@example +c'4 +@end example + +@noindent +will result in a parsing error. Instead, music should be inside other +expressions, which may be put in a file by themselves. Such +expressions are called toplevel expressions; see @ruser{File structure}, for +a list of all such expressions. + + +@node How LilyPond files work +@section How LilyPond files work + +The LilyPond input format is quite free-form, giving experienced +users a lot of flexibility to structure their files however they +wish. However, this flexibility can make things confusing for +new users. This section will explain some of this structure, but +may gloss over some details in favor of simplicity. For a complete +description of the input format, see @ruser{File structure}. + +Most examples in this manual are little snippets -- for example + +@example +c4 a b c +@end example + +As you are (hopefully) aware by now, this will not compile by +itself. These examples are shorthand for complete +examples. They all need at least curly braces to compile + +@example +@{ + c4 a b c +@} +@end example + +Most examples also make use of the @code{\relative c'} +(or @code{c''}) command. This is not necessary to merely +compile the examples, but in most cases the output will +look very odd if you omit the @code{\relative c'}. + +@lilypond[quote,fragment,ragged-right,verbatim] +\relative c'' { + c4 a b c +} +@end lilypond + +Now we get to the only real stumbling block: LilyPond +input in this form is actually @emph{another} +shorthand. Although it compiles and displays the +correct output, it is shorthand for + +@example +\score @{ + \relative c'' @{ + c4 a b c + @} +@} +@end example + +A @code{\score} must begin with a single music +expression. Remember that a music expression could +be anything from a single note to a huge + +@example +@{ + \new GrandStaff << + insert the whole score of a Wagner opera in here + >> +@} +@end example + +@noindent +Since everything is inside @code{@{ ... @}}, it counts +as one music expression. + +The @code{\score} can contain other things, such as + +@example +\score @{ + @{ c'4 a b c' @} + \layout @{ @} + \midi @{ @} + \header @{ @} +@} +@end example + +@noindent +Some people put some of those commands outside the +@code{\score} block -- for example, @code{\header} is +often placed above the @code{\score}. That's just +another shorthand that LilyPond accepts. + +@cindex variables +@cindex identifiers + +Another great shorthand is the ability to define +variables. All the templates use this + +@example +melody = \relative c' @{ + c4 a b c +@} + +\score @{ + @{ \melody @} +@} +@end example + +When LilyPond looks at this file, it takes the value of +@code{melody} (everything after the equals sign) and +inserts it whenever it sees +@code{\melody}. There's nothing special about the +names -- it could be @code{melody}, @code{global}, +@code{pianorighthand}, or @code{foofoobarbaz}. You +can use whatever variable names you want. For +more details, see +@ruser{Saving typing with identifiers and functions}. + +For a complete definition +of the input format, see @ruser{File structure}. + + +@node Score is a single musical expression +@section Score is a single musical expression + +In the previous section, @ruser{How LilyPond files work}, +we saw the general organization of LilyPond input +files. But we seemed to skip over the most important +part: how do we figure out what to write after +@code{\score}? + +We didn't skip over it at all. The big mystery is simply +that there @emph{is} no mystery. This line explains it +all: + +@quotation +@emph{A @code{\score} must begin with a single music expression.} +@end quotation + +@noindent +You may find it useful to review +@ruser{Music expressions explained}. In that section, we +saw how to build big music expressions from small +pieces -- we started from notes, then chords, etc. Now +we're going to start from a big music expression and +work our way down. + +@example +\score @{ + @{ % this brace begins the overall music expression + \new GrandStaff << + insert the whole score of a Wagner opera in here + >> + @} % this brace ends the overall music expression + \layout @{ @} +@} +@end example + +A whole Wagner opera would easily double the length of +this manual, so let's just do a singer and piano. We +don't need a @code{GrandStaff} for this ensemble, so we +shall remove it. We @emph{do} need a singer and a piano, +though. + +@example +\score @{ + @{ + << + \new Staff = "singer" << + >> + \new PianoStaff = piano << + >> + >> + @} + \layout @{ @} +@} +@end example + +Remember that we use @code{<<} and @code{>>} to show +simultaneous music. And we definitely want to show +the vocal part and piano part at the same time! + +@example +\score @{ + @{ + << + \new Staff = "singer" << + \new Voice = "vocal" @{ @} + >> + \new Lyrics \lyricsto vocal \new Lyrics @{ @} + \new PianoStaff = "piano" << + \new Staff = "upper" @{ @} + \new Staff = "lower" @{ @} + >> + >> + @} + \layout @{ @} +@} +@end example + +Now we have a lot more details. We have the singer's +staff: it contains a @code{Voice} (in LilyPond, this +term refers to a set of notes, not necessarily vocal +notes -- for example, a violin generally plays one +voice) and some lyrics. We also have a piano staff: +it contains an upper staff (right hand) and a lower +staff (left hand). + +At this stage, we could start filling in notes. Inside +the curly braces next to @code{\new Voice = vocal}, +we could start writing + +@example +\relative c'' @{ + a4 b c d +@} +@end example + +But if we did that, the @code{\score} section would +get pretty long, and it would be harder to understand +what was happening. So let's use identifiers (or +variables) instead. + +@example +melody = @{ @} +text = @{ @} +upper = @{ @} +lower = @{ @} +\score @{ + @{ + << + \new Staff = "singer" << + \new Voice = "vocal" @{ \melody @} + >> + \new Lyrics \lyricsto vocal \new Lyrics @{ \text @} + \new PianoStaff = "piano" << + \new Staff = "upper" @{ \upper @} + \new Staff = "lower" @{ \lower @} + >> + >> + @} + \layout @{ @} +@} +@end example + +@noindent +Remember that you can use almost any name you like. The +limitations on identifier names are detailed in +@ruser{File structure}. + +When writing a @code{\score} section, or when reading +one, just take it slowly and carefully. Start with +the outer layer, then work on each smaller +layer. It also really helps to be strict with +indentation -- make sure that each item on the same +layer starts on the same horizontal position in your +text editor! + + + + + diff --git a/Documentation/user/lilypond-learning.tely b/Documentation/user/lilypond-learning.tely index f37ba4dd0d..38adf5ea0d 100644 --- a/Documentation/user/lilypond-learning.tely +++ b/Documentation/user/lilypond-learning.tely @@ -130,13 +130,16 @@ of this and other documentation. * Preface:: Preface. * Introduction:: What, Why, How. * Tutorial:: A tutorial introduction. -* Putting it all together:: More explanation about LilyPond -* concepts. +* Fundamental concepts:: Basic concepts required for reading +the rest of this manual. +* Putting it all together:: More explanation. * Working on LilyPond projects:: Discusses real-life usage. * Tweaking output:: Introduction to modifying output. Appendices +* Templates:: Ready-made templates. +* Scheme tutorial:: Programming inside LilyPond. * GNU Free Documentation License:: License of this document. * LilyPond index:: @end menu @@ -150,10 +153,13 @@ Appendices @include preface.itely @include introduction.itely @include tutorial.itely +@include fundamental.itely @include putting.itely @include working.itely @include tweaks.itely +@include templates.itely +@include scheme-tutorial.itely @include fdl.itexi @node LilyPond index diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 96f322ffd8..c470c50127 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -167,9 +167,7 @@ of this and other documentation. Appendices * Literature list:: Reference works about music notation. -* Scheme tutorial:: Programming inside LilyPond. * Notation manual tables:: Tables and charts. -* Templates:: Ready-made templates. * Cheat sheet:: Summary of LilyPond syntax. * GNU Free Documentation License:: License of this document. * LilyPond command index:: @@ -191,9 +189,7 @@ Appendices @include literature.itely -@include scheme-tutorial.itely @include notation-appendices.itely -@include templates.itely @include cheatsheet.itely @include fdl.itexi diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely index ba315b7bc9..0b868a6678 100644 --- a/Documentation/user/non-music.itely +++ b/Documentation/user/non-music.itely @@ -33,7 +33,6 @@ The main format of input for LilyPond are text files. By convention, these files end with @samp{.ly}. @menu -* File structure (introduction):: * File structure:: * A single music expression:: * Multiple scores in a book:: @@ -44,41 +43,6 @@ these files end with @samp{.ly}. @end menu -@node File structure (introduction) -@subsection File structure (introduction) - -A basic example of a lilypond input file is - -@example -\version "2.11.23" -\score @{ - @{ @} % this is a single music expression; - % all the music goes in here. - \header @{ @} - \layout @{ @} - \midi @{ @} -@} -@end example - -@noindent -There are many variations of this basic pattern, but this -example serves as a useful starting place. - -The major part of this manual is concerned with entering various -forms of music in LilyPond. However, many music expressions are not -valid input on their own, for example, a @code{.ly} file containing -only a note -@example -c'4 -@end example - -@noindent -will result in a parsing error. Instead, music should be inside other -expressions, which may be put in a file by themselves. Such -expressions are called toplevel expressions; see @ref{File structure}, for -a list of all such expressions. - - @node File structure @subsection File structure diff --git a/Documentation/user/piano.itely b/Documentation/user/piano.itely index ed1ca6f272..b1538d2a39 100644 --- a/Documentation/user/piano.itely +++ b/Documentation/user/piano.itely @@ -28,7 +28,7 @@ handle this cross-staffing behavior. In this section we discuss the @refbugs Dynamics are not centered, but workarounds do exist. See the -@q{piano centered dynamics} template in @ref{Piano templates}. +@q{piano centered dynamics} template in @rlearning{Piano templates}. @cindex cross staff stem @cindex stem, cross staff diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index abc9776367..537da3bc4e 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -12,7 +12,7 @@ Advanced tweaks may be performed by using Scheme. If you are not familiar with Scheme, you may wish to read our -@ref{Scheme tutorial}. +@rlearning{Scheme tutorial}. @menu * Music functions:: diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely index c49624cbe2..68d4cca543 100644 --- a/Documentation/user/putting.itely +++ b/Documentation/user/putting.itely @@ -16,8 +16,6 @@ create @code{\score} blocks. @menu * Extending the templates:: -* How LilyPond files work:: -* Score is a single musical expression:: * An orchestral part:: @end menu @@ -209,258 +207,6 @@ celloMusic = \relative c { -@node How LilyPond files work -@section How LilyPond files work - -The LilyPond input format is quite free-form, giving experienced -users a lot of flexibility to structure their files however they -wish. However, this flexibility can make things confusing for -new users. This section will explain some of this structure, but -may gloss over some details in favor of simplicity. For a complete -description of the input format, see @ruser{File structure}. - -Most examples in this manual are little snippets -- for example - -@example -c4 a b c -@end example - -As you are (hopefully) aware by now, this will not compile by -itself. These examples are shorthand for complete -examples. They all need at least curly braces to compile - -@example -@{ - c4 a b c -@} -@end example - -Most examples also make use of the @code{\relative c'} -(or @code{c''}) command. This is not necessary to merely -compile the examples, but in most cases the output will -look very odd if you omit the @code{\relative c'}. - -@lilypond[quote,fragment,ragged-right,verbatim] -\relative c'' { - c4 a b c -} -@end lilypond - -Now we get to the only real stumbling block: LilyPond -input in this form is actually @emph{another} -shorthand. Although it compiles and displays the -correct output, it is shorthand for - -@example -\score @{ - \relative c'' @{ - c4 a b c - @} -@} -@end example - -A @code{\score} must begin with a single music -expression. Remember that a music expression could -be anything from a single note to a huge - -@example -@{ - \new GrandStaff << - insert the whole score of a Wagner opera in here - >> -@} -@end example - -@noindent -Since everything is inside @code{@{ ... @}}, it counts -as one music expression. - -The @code{\score} can contain other things, such as - -@example -\score @{ - @{ c'4 a b c' @} - \layout @{ @} - \midi @{ @} - \header @{ @} -@} -@end example - -@noindent -Some people put some of those commands outside the -@code{\score} block -- for example, @code{\header} is -often placed above the @code{\score}. That's just -another shorthand that LilyPond accepts. - -@cindex variables -@cindex identifiers - -Another great shorthand is the ability to define -variables. All the templates use this - -@example -melody = \relative c' @{ - c4 a b c -@} - -\score @{ - @{ \melody @} -@} -@end example - -When LilyPond looks at this file, it takes the value of -@code{melody} (everything after the equals sign) and -inserts it whenever it sees -@code{\melody}. There's nothing special about the -names -- it could be @code{melody}, @code{global}, -@code{pianorighthand}, or @code{foofoobarbaz}. You -can use whatever variable names you want. For -more details, see -@ruser{Saving typing with identifiers and functions}. - -For a complete definition -of the input format, see @ruser{File structure}. - - -@node Score is a single musical expression -@section Score is a single musical expression - -In the previous section, @ruser{How LilyPond files work}, -we saw the general organization of LilyPond input -files. But we seemed to skip over the most important -part: how do we figure out what to write after -@code{\score}? - -We didn't skip over it at all. The big mystery is simply -that there @emph{is} no mystery. This line explains it -all: - -@quotation -@emph{A @code{\score} must begin with a single music expression.} -@end quotation - -@noindent -You may find it useful to review -@ruser{Music expressions explained}. In that section, we -saw how to build big music expressions from small -pieces -- we started from notes, then chords, etc. Now -we're going to start from a big music expression and -work our way down. - -@example -\score @{ - @{ % this brace begins the overall music expression - \new GrandStaff << - insert the whole score of a Wagner opera in here - >> - @} % this brace ends the overall music expression - \layout @{ @} -@} -@end example - -A whole Wagner opera would easily double the length of -this manual, so let's just do a singer and piano. We -don't need a @code{GrandStaff} for this ensemble, so we -shall remove it. We @emph{do} need a singer and a piano, -though. - -@example -\score @{ - @{ - << - \new Staff = "singer" << - >> - \new PianoStaff = piano << - >> - >> - @} - \layout @{ @} -@} -@end example - -Remember that we use @code{<<} and @code{>>} to show -simultaneous music. And we definitely want to show -the vocal part and piano part at the same time! - -@example -\score @{ - @{ - << - \new Staff = "singer" << - \new Voice = "vocal" @{ @} - >> - \new Lyrics \lyricsto vocal \new Lyrics @{ @} - \new PianoStaff = "piano" << - \new Staff = "upper" @{ @} - \new Staff = "lower" @{ @} - >> - >> - @} - \layout @{ @} -@} -@end example - -Now we have a lot more details. We have the singer's -staff: it contains a @code{Voice} (in LilyPond, this -term refers to a set of notes, not necessarily vocal -notes -- for example, a violin generally plays one -voice) and some lyrics. We also have a piano staff: -it contains an upper staff (right hand) and a lower -staff (left hand). - -At this stage, we could start filling in notes. Inside -the curly braces next to @code{\new Voice = vocal}, -we could start writing - -@example -\relative c'' @{ - a4 b c d -@} -@end example - -But if we did that, the @code{\score} section would -get pretty long, and it would be harder to understand -what was happening. So let's use identifiers (or -variables) instead. - -@example -melody = @{ @} -text = @{ @} -upper = @{ @} -lower = @{ @} -\score @{ - @{ - << - \new Staff = "singer" << - \new Voice = "vocal" @{ \melody @} - >> - \new Lyrics \lyricsto vocal \new Lyrics @{ \text @} - \new PianoStaff = "piano" << - \new Staff = "upper" @{ \upper @} - \new Staff = "lower" @{ \lower @} - >> - >> - @} - \layout @{ @} -@} -@end example - -@noindent -Remember that you can use almost any name you like. The -limitations on identifier names are detailed in -@ruser{File structure}. - -When writing a @code{\score} section, or when reading -one, just take it slowly and carefully. Start with -the outer layer, then work on each smaller -layer. It also really helps to be strict with -indentation -- make sure that each item on the same -layer starts on the same horizontal position in your -text editor! - - - - @node An orchestral part diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely index 7b3987657d..fec67c7f76 100644 --- a/Documentation/user/vocal.itely +++ b/Documentation/user/vocal.itely @@ -473,7 +473,7 @@ behavior}) is switched off. @cindex choral score A complete example of a SATB score setup is in section -@ref{Vocal ensembles}. +@rlearning{Vocal ensembles}. @refcommands diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely index 1e483bd4cb..785c756403 100644 --- a/Documentation/user/working.itely +++ b/Documentation/user/working.itely @@ -70,7 +70,7 @@ problems: @itemize @bullet @item @strong{Include @code{\version} numbers in every file}. Note that all -templates contain a @code{\version "2.11.23"} string. We +templates contain @code{\version} information. 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 -- 2.39.2