From: Graham Percival Date: Sat, 29 Sep 2007 01:26:09 +0000 (-0700) Subject: Begin filling in Fundamental concepts. X-Git-Tag: release/2.11.35-1~46^2~119 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=6be33a0b6d6781fc8f2fce09bd996189c1c59c73;p=lilypond.git Begin filling in Fundamental concepts. --- diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely index c4a4e811c9..fe4a80c2e1 100644 --- a/Documentation/user/expressive.itely +++ b/Documentation/user/expressive.itely @@ -33,8 +33,8 @@ @cindex ornaments A variety of symbols can appear above and below notes to indicate -different characteristics of the performance. They are added to a note -by adding a dash and the character signifying the +different characteristics of the performance. They are added to a +note by adding a dash and the character signifying the articulation. They are demonstrated here @lilypondfile[quote,ragged-right]{script-abbreviations.ly} @@ -42,9 +42,9 @@ articulation. They are demonstrated here The meanings of these shorthands can be changed. See @file{ly/@/script@/-init@/.ly} for examples. -The script is automatically placed, but the direction can be forced as -well. Like other pieces of LilyPond code, @code{_} will place them -below the staff, and @code{^} will place them above. +The script is automatically placed, but the direction can be +forced as well. Like other pieces of LilyPond code, @code{_} will +place them below the staff, and @code{^} will place them above. @lilypond[quote,ragged-right,fragment,verbatim] c''4^^ c''4_^ diff --git a/Documentation/user/fundamental.itely b/Documentation/user/fundamental.itely index 78ee2335e8..4aa1eb68c2 100644 --- a/Documentation/user/fundamental.itely +++ b/Documentation/user/fundamental.itely @@ -5,22 +5,27 @@ @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) +@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}. 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. + @{@var{...music expression...}@} % all the music goes here! \header @{ @} \layout @{ @} \midi @{ @} @@ -31,71 +36,35 @@ A basic example of a lilypond input file is 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 +At this point, you may be confused, since you have never seen a +@code{\score@{@}} before. This is because LilyPond automatically +adds the extra commands when you give it simple input. LilyPond +treats input like this: @example -@{ - c4 a b c +\relative c'' @{ + c4 a d 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 +@noindent +as shorthand for this: @example \score @{ \relative c'' @{ c4 a b c @} + \layout @{ @} @} @end example +In other words, if the input contains a single music expression, +LilyPond will interpret the file as though the music expression +was wrapped up inside a @code{\score@{@}}. + +@smallspace + 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 @@ -103,7 +72,7 @@ be anything from a single note to a huge @example @{ \new GrandStaff << - insert the whole score of a Wagner opera in here + @var{...insert the whole score of a Wagner opera in here...} >> @} @end example @@ -112,28 +81,31 @@ be anything from a single note to a huge Since everything is inside @code{@{ ... @}}, it counts as one music expression. -The @code{\score} can contain other things, such as +As we saw previously, the @code{\score} can contain other things, +such as @example \score @{ @{ c'4 a b c' @} + \header @{ @} \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. +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. + +@smallspace @cindex variables @cindex identifiers -Another great shorthand is the ability to define -variables. All the templates use this +Another great shorthand is the ability to define identifiers. All +the templates use this @example melody = \relative c' @{ @@ -146,60 +118,57 @@ melody = \relative c' @{ @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 +@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}. + +@seealso + +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 saw the general organization of LilyPond input files in the +previous section, @ref{How LilyPond files work}. 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: +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. +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 + @{ % this brace begins the overall music expression \new GrandStaff << - insert the whole score of a Wagner opera in here + @var{...insert the whole score of a Wagner opera in here...} >> - @} % this brace ends the overall music expression + @} % 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. +A whole Wagner opera would easily double the length of this +manual, so let's just add 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 @{ @@ -215,9 +184,9 @@ though. @} @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! +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, not one after the other! @example \score @{ @@ -237,17 +206,15 @@ the vocal part and piano part at the same time! @} @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). +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 +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'' @{ @@ -255,10 +222,9 @@ we could start writing @} @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. +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 = @{ @} @@ -284,17 +250,14 @@ lower = @{ @} @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! - +limitations on identifier names are detailed in @ruser{File +structure}. + +When writing (or reading) a @code{\score} section, 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/macros.itexi b/Documentation/user/macros.itexi index 55962b53a1..6ae52606b0 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -71,6 +71,12 @@ @c **** Headings in a doc subsection **** +@c not really a heading, but... +@macro smallspace +@sp 1 +@end macro + +@c absolete; being removed. @macro refcommands @noindent @subsubheading Predefined commands @@ -91,7 +97,7 @@ @macro refbugs @noindent -@subsubheading Bugs +@subsubheading Known issues and warnings @end macro diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 6f65af792c..f922b7bd83 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -120,7 +120,7 @@ In addition, LilyPond input is @strong{case sensitive}. @code{ @{c d e @}} is valid input; @code{@{ C D E @}} will produce an error message. -@sp 1 +@smallspace @subheading Entering music and viewing output @@ -583,7 +583,7 @@ a1 a @end lilypond -@sp 1 +@smallspace @subheading Warning: key signatures and pitches @@ -678,7 +678,7 @@ simultaneous phrasing slurs. a8(\( ais b c) cis2 b'2 a4 cis,\) @end lilypond -@sp 1 +@smallspace @cindex slurs versus ties @subheading Warnings: slurs vs. ties