From 7c0d9593d7a298549f979b209a340346b5f3c3f6 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Wed, 21 Nov 2007 14:58:30 -0800 Subject: [PATCH] Misc updates. --- Documentation/user/policy.txt | 21 +++- Documentation/user/tutorial.itely | 157 +++++++++++++----------------- Documentation/user/tweaks.itely | 11 +++ 3 files changed, 97 insertions(+), 92 deletions(-) diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index 6665bc13e0..4f0367fd8d 100644 --- a/Documentation/user/policy.txt +++ b/Documentation/user/policy.txt @@ -8,11 +8,22 @@ There are four parts to the documentation: the Learning Manual, the Notation Reference, the Program Reference, and the Music Glossary. -* Learning Manual: long, chatty, friendly explanations go here. - This is aimed at users learning something for the first time -- - not necessarily just learning lilypond notation, but also things - like learning how to deal with projects, tweaking, preparing parts - for orchestras, etc. Less formal language may be used here. +* Learning Manual: + The LM is written in a tutorial style which introduces the most + important concepts, structure and syntax of the elements of a + LilyPond score in a carefully graded sequence of steps. + Explanations of all musical concepts used in the Manual can be + found in the Music Glossary, and readers are assumed to have no + prior knowledge of LilyPond. The objective is to take readers to + a level where the Notation Reference can be understood and + employed to both adapt the templates in the Appendix to their + needs and to begin to construct their own scores. Commonly used + tweaks are introduced and explained. Examples are provided + throughout which, while being focussed on the topic being + introduced, are long enough to seem real in order to retain the + readers' interest. Each example builds on the previous material, + and comments are used liberally. Every new aspect is thoroughly + explained before it is used. Users are encouraged to read the complete Learning Manual from start-to-finish. diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 3c35e81f2c..5769244075 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -7,28 +7,6 @@ version that you are working on. See TRANSLATION for details. @end ignore -@ignore - -Tutorial Specification: - -The LM is written in a tutorial style which introduces the most -important concepts, structure and syntax of the elements of a -LilyPond score in a carefully graded sequence of steps. -Explanations of all musical concepts used in the Manual can be -found in the Music Glossary, and readers are assumed to have no -prior knowledge of LilyPond. The objective is to take readers to -a level where the Notation Reference can be understood and -employed to both adapt the templates in the Appendix to their -needs and to begin to construct their own scores. Commonly used -tweaks are introduced and explained. Examples are provided -throughout which, while being focussed on the topic being -introduced, are long enough to seem real in order to retain the -readers' interest. Each example builds on the previous material, -and comments are used liberally. Every new aspect is thoroughly -explained before it is used. - -@end ignore - @ignore Tutorial guidelines: (different from policy.txt!) - unless you have a really good reason, use either @@ -226,10 +204,10 @@ Music Glossary: @rglos{pitch}, @rglos{interval}, @rglos{accidental}. The easiest way to enter notes is by using @code{\relative} mode. -In this mode, the octave is chosen automatically by assuming the -following note is always to be placed closest to the previous note, -i.e., it is to be placed in the octave which is within three -staff spaces of the previous note. We begin by entering the most +In this mode, the octave is chosen automatically by assuming the +following note is always to be placed closest to the previous +note, i.e., it is to be placed in the octave which is within three +staff spaces of the previous note. We begin by entering the most elementary piece of music, a @notation{scale}, in which every note is within just one staff space of the previous note. @@ -243,8 +221,8 @@ is within just one staff space of the previous note. The initial note is @notation{middle C}. Each successive note is placed closest to the previous note -- in other words, the first @code{c} is the closest C to middle C. This is followed by the -closest D to the previous note. We can create melodies which -have larger intervals, still using only @code{\relative} mode: +closest D to the previous note. We can create melodies which have +larger intervals, still using only @code{\relative} mode: @lilypond[verbatim,quote,ragged-right] \relative c' { @@ -289,10 +267,10 @@ above the B, and an A, G or F will be assumed to be below. @end lilypond Exactly the same happens even when any of these notes are -sharpened or flattened. @notation{Accidentals} are @strong{totally -ignored} in the calculation of relative position. Precisely the -same staff space counting is done from a note at any other -position on the staff. +sharpened or flattened. @notation{Accidentals} are +@strong{totally ignored} in the calculation of relative position. +Precisely the same staff space counting is done from a note at any +other position on the staff. To add intervals that are larger than three staff spaces, we can raise the @notation{octave} by adding a single quote @code{'} (or @@ -316,8 +294,9 @@ this. @subheading Durations (rhythms) -Music Glossary: @rglos{beam}, @rglos{duration}, @rglos{whole note}, -@rglos{half note}, @rglos{quarter note}, @rglos{dotted note}. +Music Glossary: @rglos{beam}, @rglos{duration}, +@rglos{whole note}, @rglos{half note}, @rglos{quarter note}, +@rglos{dotted note}. The @notation{duration} of a note is specified by a number after the note name. @code{1} for a @notation{whole note}, @code{2} for @@ -352,7 +331,8 @@ explicitly (i.e., with a number). Music Glossary: @rglos{rest}. -A @notation{rest} is entered just like a note with the name @code{r}: +A @notation{rest} is entered just like a note with the name +@code{r}: @lilypond[verbatim,quote,ragged-right] \relative c'' { @@ -417,11 +397,10 @@ Here is a small example showing all these elements together: @seealso -Notation Reference: @ruser{Writing pitches}, @ruser{Writing rhythms}, -@ruser{Writing rests}, @ruser{Time signature}, @ruser{Clef}. - +Notation Reference: @ruser{Writing pitches}, +@ruser{Writing rhythms}, @ruser{Writing rests}, +@ruser{Time signature}, @ruser{Clef}. -@c HERE's where I started @node Working on text files @subsection Working on text files @@ -587,13 +566,13 @@ on one staff. Music Glossary: @rglos{sharp}, @rglos{flat}, @rglos{double sharp}, @rglos{double flat}, @rglos{accidental}. -A @notation{sharp} pitch is made by adding @code{is} to the name, and -a @notation{flat} pitch by adding @code{es}. As you might expect, a -@notation{double sharp} or @notation{double flat} is made by adding -@code{isis} or @code{eses}. This syntax is derived from note -naming conventions in Nordic and Germanic languages, like German -and Dutch. To use other names for @notation{accidentals}, see -@ruser{Note names in other languages}. +A @notation{sharp} pitch is made by adding @code{is} to the name, +and a @notation{flat} pitch by adding @code{es}. As you might +expect, a @notation{double sharp} or @notation{double flat} is +made by adding @code{isis} or @code{eses}. This syntax is derived +from note naming conventions in Nordic and Germanic languages, +like German and Dutch. To use other names for +@notation{accidentals}, see @ruser{Note names in other languages}. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] cis1 ees fisis, aeses @@ -602,7 +581,8 @@ cis1 ees fisis, aeses @cindex key signature, setting @subheading Key signatures -Music Glossary: @rglos{key signature}, @rglos{major}, @rglos{minor}. +Music Glossary: @rglos{key signature}, @rglos{major}, +@rglos{minor}. The @notation{key signature} is set with the command @code{\key} followed by a pitch and @code{\major} or @code{\minor}. @@ -624,19 +604,20 @@ Music Glossary: @rglos{accidental}, @rglos{key signature}, To determine whether to print an @notation{accidental}, LilyPond examines the pitches and the @notation{key signature}. The key -signature only affects the @emph{printed} accidentals, not the note's -@notation{pitch}! This is a feature that often causes confusion to -newcomers, so let us explain it in more detail. +signature only affects the @emph{printed} accidentals, not the +note's @notation{pitch}! This is a feature that often causes +confusion to newcomers, so let us explain it in more detail. LilyPond makes a sharp distinction between musical content and layout. The alteration (@notation{flat}, @notation{natural} or @notation{sharp}) of a note is part of the pitch, and is therefore -musical content. Whether an accidental (a @emph{printed} flat, natural -or sharp sign) is printed in front of the corresponding note is a -question of layout. Layout is something that follows rules, so -accidentals are printed automatically according to those rules. The -pitches in your music are works of art, so they will not be added -automatically, and you must enter what you want to hear. +musical content. Whether an accidental (a @emph{printed} flat, +natural or sharp sign) is printed in front of the corresponding +note is a question of layout. Layout is something that follows +rules, so accidentals are printed automatically according to those +rules. The pitches in your music are works of art, so they will +not be added automatically, and you must enter what you want to +hear. In this example: @@ -668,8 +649,9 @@ accidentals can be printed according to different rules, see @seealso -Notation Reference: @ruser{Note names in other languages}, @ruser{Accidentals}, -@ruser{Automatic accidentals}, @ruser{Key signature}. +Notation Reference: @ruser{Note names in other languages}, +@ruser{Accidentals}, @ruser{Automatic accidentals}, +@ruser{Key signature}. Music Glossary: @rglos{Pitch names}. @@ -695,9 +677,9 @@ c4 ~ c8 a8 ~ a2 Music Glossary: @rglos{slur}. -A @notation{slur} is a curve drawn across many notes. The starting -note and ending note are marked with @code{(} and @code{)} -respectively. +A @notation{slur} is a curve drawn across many notes. The +starting note and ending note are marked with @code{(} and +@code{)} respectively. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] d4( c16) cis( d e c cis d) e( d4) @@ -710,9 +692,9 @@ d4( c16) cis( d e c cis d) e( d4) Music Glossary: @rglos{phrasing}, @rglos{legato}. Slurs to indicate longer @notation{phrasing} can be entered with -@code{\(} and @code{\)}. You can have both @notation{legato} slurs and -phrasing slurs at the same time, but you cannot have simultaneous legato -slurs or simultaneous phrasing slurs. +@code{\(} and @code{\)}. You can have both @notation{legato} +slurs and phrasing slurs at the same time, but you cannot have +simultaneous legato slurs or simultaneous phrasing slurs. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] a8(\( ais b c) cis2 b'2 a4 cis,\) @@ -725,11 +707,11 @@ a8(\( ais b c) cis2 b'2 a4 cis,\) Music Glossary: @rglos{articulation}, @rglos{slur}, @rglos{tie}. -A @notation{slur} looks like a @notation{tie}, but it has a different -meaning. A tie simply makes the first note longer, and can only be -used on pairs of notes with the same pitch. Slurs indicate the -@notation{articulation} of notes, and can be used on larger groups of -notes. Slurs and ties can be nested. +A @notation{slur} looks like a @notation{tie}, but it has a +different meaning. A tie simply makes the first note longer, and +can only be used on pairs of notes with the same pitch. Slurs +indicate the @notation{articulation} of notes, and can be used on +larger groups of notes. Slurs and ties can be nested. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] c2~( c8 fis fis4 ~ fis2 g2) @@ -764,18 +746,18 @@ c-. c-- c-> c-^ c-+ c-_ Music Glossary: @rglos{fingering}. -Similarly, @notation{fingering} indications can be added to a note using -a dash (@code{-}) and the digit to be printed: +Similarly, @notation{fingering} indications can be added to a note +using a dash (@code{-}) and the digit to be printed: @lilypond[verbatim,quote,ragged-right,fragment,relative=2] c-3 e-5 b-2 a-1 @end lilypond Articulations and fingerings are usually placed automatically, but -you can specify a direction by replacing the dash (@code{-}) with @code{^} (up) or @code{_} -(down). You can also use multiple articulations on the same note. -However, in most cases it is best to let LilyPond determine the -articulation directions. +you can specify a direction by replacing the dash (@code{-}) with +@code{^} (up) or @code{_} (down). You can also use multiple +articulations on the same note. However, in most cases it is best +to let LilyPond determine the articulation directions. @lilypond[verbatim,quote,ragged-right,fragment,relative=2] c_-^1 d^. f^4_2-> e^-_+ @@ -905,7 +887,8 @@ Triplets make notes occupy 2/3 of their notated duration, so a @cindex appoggiatura @subheading Grace notes -Music Glossary: @rglos{grace notes}, @rglos{acciacccatura}, @rglos{appoggiatura}. +Music Glossary: @rglos{grace notes}, @rglos{acciacccatura}, +@rglos{appoggiatura}. @notation{Grace notes} are created with the @code{\grace} command, although they can also be created by prefixing a music expression @@ -1303,10 +1286,10 @@ bright as day}. Let's extend it: We see the extra lyrics do not align properly with the notes. The word @q{shine} should be sung on two notes, not one. This is -called a @notation{melisma}, a single syllable sung to more than one -note. There are several ways to spread a syllable over multiple -notes, the simplest being to add a slur across them (see @ref{Ties -and slurs}): +called a @notation{melisma}, a single syllable sung to more than +one note. There are several ways to spread a syllable over +multiple notes, the simplest being to add a slur across them (see +@ref{Ties and slurs}): @lilypond[verbatim,quote,ragged-right] << @@ -1328,10 +1311,10 @@ Here we have also used manual beaming (the square brackets @code{[ (see @ref{Automatic and manual beams}). If a syllable extends over several notes or a single very long -note an @notation{extender line} is usually drawn from the syllable -extending under all the notes for that syllable. It is entered as -two underscores @code{__}. Here is an example from the first -three bars of Dido's Lament, from Purcell's Dido and Æneas: +note an @notation{extender line} is usually drawn from the +syllable extending under all the notes for that syllable. It is +entered as two underscores @code{__}. Here is an example from the +first three bars of Dido's Lament, from Purcell's Dido and Æneas: @lilypond[verbatim,quote,ragged-right] << @@ -1649,9 +1632,9 @@ places. The following example uses the above variables: @subsection After the tutorial After finishing the tutorial, you should probably try writing a -piece or two. Start by adding notes to one of the @ref{Templates}. -If you need any notation that was not covered in the -tutorial, look at the Notation Reference, starting with +piece or two. Start by adding notes to one of the +@ref{Templates}. If you need any notation that was not covered in +the tutorial, look at the Notation Reference, starting with @ruser{Musical notation}. If you want to write for an instrument ensemble that is not covered in the templates, take a look at @ref{Extending the templates}. diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index 321a2b46c7..0d2c1fa05d 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -623,3 +623,14 @@ Here's the final result: @end lilypond + + +FIXME: +- There is a section in the manual on \set vs \override (3.3.7), +which is incomplete. First it doesn't mention \overrideProperty, +nor does it mention properties which are not capitalized at all. +And it should explain that \override should be used to set +properties with hyphenated names, like auto-knee-gap. (I had to +experiment to find out how to do this.) + + -- 2.39.2