From 7416f2c1922cdf7a1f2ebb36088e4e11ac9c03cd Mon Sep 17 00:00:00 2001 From: hanwen Date: Tue, 30 Mar 2004 10:27:26 +0000 Subject: [PATCH] (Interpretation contexts): rewrite introduction. --- ChangeLog | 15 +++++++ Documentation/user/changing-defaults.itely | 49 +++++++++++++--------- Documentation/user/introduction.itely | 13 +++--- Documentation/user/tutorial.itely | 48 ++++++++++----------- THANKS | 1 + VERSION | 2 +- scm/define-markup-commands.scm | 4 +- 7 files changed, 78 insertions(+), 54 deletions(-) diff --git a/ChangeLog b/ChangeLog index f8d53127c5..ce15579bf4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2004-03-30 Han-Wen Nienhuys + + * Documentation/user/changing-defaults.itely (Interpretation + contexts): rewrite introduction. + +2004-03-30 Ferenc Wagner + + * scm/define-markup-commands.scm: Use TeX accents instead of + straight iso-8859-1 encoding in the doc string. + +2004-03-30 Han-Wen Nienhuys + + * Documentation/user/tutorial.itely (A lead sheet): remove extra + space after dotted duration. + 2004-03-29 Jan Nieuwenhuizen * Documentation/user/introduction.itely: diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 0f790f8df4..ed5b9a0db8 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -130,7 +130,7 @@ traditional 1+2. @end lisp The arrow @result{} shows that the result of evaluating @code{(+ 1 2)} -is @code{3}. Calculations may be nested: the result of a function may +is @code{3}. Calculations may be nested; the result of a function may be used for another calculation. @lisp @@ -139,7 +139,7 @@ be used for another calculation. @result{} #13 @end lisp -These calculations are examples of evaluations: an expression like +These calculations are examples of evaluations; an expression like @code{(* 3 4)} is replaced by its value @code{12}. A similar thing happens with variables. After defining a variable @@ -245,15 +245,31 @@ clef, and time signature are added. LilyPond @emph{interprets} the input. During this step, the musical information is inspected in time order, similar to reading a score from left to right. While reading, the program remembers where measure boundaries are, and what pitches -need explicit accidentals. +need explicit accidentals. This information can be presented on +several levels. For example, the effect of an accidental is limited +to a single stave, while a bar line must be synchronized across the +entire score. + +Within LilyPond, these rules and bits of information are grouped in +so-called Contexts. Examples of context are @context{Voice}, +@context{Staff}, and @context{Score}. They are hierarchical, for +example, a @context{Staff} can contain many @context{Voice}s, and a +@context{Score} can contain many @context{Staff} contexts. + +Each context has the responsibility for enforcing some notation rules, +creating some notation objects and maintaining the associated +properties. So, the synchronization of bar lines is handled at +@context{Score} context. The @context{Voice} may introduce an +accidentals and then the @context{Staff} context maintains the rule to +show or suppress the accidental for the remainder of the measure. + +For simple scores, contexts are created implicitly, and you need not +be aware of them. For larger pieces, such as piano music, they must be +created explicitly to make sure that you get as many staves as you +need, and that they are in the correct order. For typesetting pieces +with specialized notation, it can be useful to modify existing or +define new contexts. -This is contextual information and it can be presented on several -levels. For example, the effect of an accidental is limited to a -single stave, while a bar line must be synchronized across the entire -score. To match this hierarchy, LilyPond's interpretation step is -hierarchical. There are interpretation contexts, like -@context{Voice}, @context{Staff}, and @context{Score}, and each level -can maintain its own properties. Full description of all available contexts is in the program reference, see @@ -282,7 +298,7 @@ Translation @arrow{} Context. For scores with only one voice and one staff, correct contexts are created automatically. For more complex scores, it is necessary to -instantiate them by hand. There are three commands which do this. +create them by hand. There are three commands which do this. The easiest command is @code{\new}, and it also the quickest to type. It is prepended to a music expression, for example @@ -914,15 +930,7 @@ First, we will give a a few versatile commands, which are sufficient for many situations. The next section will discuss general use of @code{\override}. - - --nmost adjustments simply @c HJ: what is this? - - - -The commands changes @c HJ: what is this? - - +@ignore There are situations where default layout decisions are not sufficient. In this section we discuss ways to override these defaults. @@ -954,6 +962,7 @@ layout property name: #'layout-property-name @end example +@end ignore @menu * Common tweaks:: diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 6e41c8d0ad..264c622902 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -40,9 +40,8 @@ has obvious advantages; prints are cheaper to make, editorial work can be delivered by email. Unfortunately, the pervasive use of computers has also decreased the graphical quality of scores. Computer printouts have a bland, mechanical look, which makes them unpleasant -to play from. The most important features of a music print is the -font, i.e, the symbols or glyphs, and the placement or spacing of the -symbols. +to play from. + @c introduce illustrating aspects of engraving, font... The images below illustrate the difference between traditional @@ -197,7 +196,7 @@ software. The remaining cases can be tuned by hand. Over the course of years, the software can be refined to do more and more automatically, so manual overrides are less and less necessary. -When we started we wrote the LilyPond entirely using the C++ +When we started we wrote the LilyPond program entirely in the C++ programming language, the program's functionality was set in stone by the developers. That proved to be unsatisfactory for a number of reasons: @@ -222,9 +221,9 @@ notation works. @end itemize These problems have been addressed by integrating the GUILE -interpreter for the scheme programming language and rewriting parts of -LilyPond in scheme. The new, flexible formatting is built around the -notion of graphical objects, described by scheme variables and +interpreter for the Scheme programming language and rewriting parts of +LilyPond in Scheme. The new, flexible formatting is built around the +notion of graphical objects, described by Scheme variables and functions. This architecture encompasses formatting rules, typographical style and individual formatting decisions. The user has direct access to most of these controls. diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 76ecb16e89..ce98aa4fdf 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -38,13 +38,6 @@ the @ref{Cheat sheet}, which is a table listing all commands for quick reference. -@c unnecesary cruft? -In this tutorial, we will show step by step how to enter such files, -and illustrate the process with fragments of input and the -corresponding output. At the end of every section, a paragraph will -list where to find further information on the topics discussed. - - @menu * First steps:: * Running LilyPond:: @@ -107,7 +100,7 @@ a1 a2 a4 a16 a32 @end quotation If you do not specify a @rglos{duration}, the duration last entered is -used; the first note's duration defaults to a quarter +used; the duration of the first note defaults to a quarter @c FIXME: let's omit the first note rule? @c The first note will be a quarter @@ -144,13 +137,13 @@ s16_" " Add a dot @samp{.} after the duration to get a @rglos{dotted note} @example -a2. a4 a8. a16 +a2. a4 a8. a16 @end example @quotation @lilypond[notime] \set Score.timing = ##f -\transpose c c' { a2. a4 a8. a16 s16_" " } +\transpose c c' { a2. a4 a8. a16 s16_" " } @end lilypond @end quotation @@ -275,6 +268,13 @@ see @ref{Time signature}. @c instruct (how) to use them; let advanced user figure-out what @c commands to type? +@c +@c We don't have enough space to explain either VIM +@c or Emacs non-advanced users, and I fear that both editors will only +@c confuse newbies. I vote for keeping the material in footnotes. +@c +@c --hwn + In the last section we explained what kind of things you could enter in a LilyPond file. In this section we will explain what commands to run and how to view or print the output. If you have not used @@ -283,14 +283,14 @@ file yourself, read this section. The instructions that follow are for Unix-like systems. Some additional instructions for Microsoft Windows are given at the end of this section. -@c FIXME: remove footnotes/integrate in text Begin by opening a terminal window and starting a text editor. For example, you could open an xterm and execute @code{joe}@footnote{There are macro files for VIM addicts, and there is a @code{LilyPond-mode} for Emacs addicts. If it has not been -installed already, refer to the file @file{INSTALL.txt}}. In your -text editor, enter the following input and save the file as -@file{test.ly} +installed already, refer to +@c FIXME lousy reference. +the file @file{INSTALL.txt}}. In your text editor, enter the following +input and save the file as @file{test.ly} @example \score @{ @@ -581,8 +581,8 @@ An example of the use of quotes is in the following Mozart fragment @lilypond[raggedright,fragment,verbatim] \key a \major \time 6/8 -cis''8. d''16 cis''8 e''4 e''8 -b'8. cis''16 b'8 d''4 d''8 +cis''8. d''16 cis''8 e''4 e''8 +b'8. cis''16 b'8 d''4 d''8 @end lilypond @end quotation @@ -623,8 +623,8 @@ entered as \relative c'' { \key a \major \time 6/8 - cis8. d16 cis8 e4 e8 - b8. cis16 b8 d4 d8 + cis8. d16 cis8 e4 e8 + b8. cis16 b8 d4 d8 } @end lilypond @end quotation @@ -695,11 +695,11 @@ notes @end lilypond @end quotation -This technique becomes useful for non-monophonic music. To enter music +This technique is useful for non-monophonic music. To enter music with more voices or more staves, we also combine expressions in -parallel. Two voices that should play at the same time, are entered as -a simultaneous combination of two sequences. A ``simultaneous'' music -expression is formed by enclosing expressions in @code{<<} and +parallel. Two voices that should play at the same time, are entered +as a simultaneous combination of two sequences. A ``simultaneous'' +music expression is formed by enclosing expressions in @code{<<} and @code{>>}. In the following example, three sequences (all containing two notes) are combined simultaneously @@ -819,7 +819,7 @@ We can now typeset a melody with two staves \clef violin \relative c'' { e2 d4 c2 b4 a8[ a] - b[ b] g[ g] a2. } + b[ b] g[ g] a2. } } \new Staff { \clef bass @@ -1189,7 +1189,7 @@ In popular music, it is common to denote accompaniment as chord-names. Such chords can be entered like notes, @example -c2 f4. g8 +c2 f4. g8 @end example @noindent diff --git a/THANKS b/THANKS index b06d6fecad..a08635f2f3 100644 --- a/THANKS +++ b/THANKS @@ -27,6 +27,7 @@ Delma Avers Doug Linhardt Eric Wurbel Erik Sandberg +Ferenc Wagner Hans Forbrich John Williams José Luis Cruz diff --git a/VERSION b/VERSION index a2757e59c0..3c7fff45ac 100644 --- a/VERSION +++ b/VERSION @@ -1,6 +1,6 @@ PACKAGE_NAME=LilyPond MAJOR_VERSION=2 MINOR_VERSION=1 -PATCH_LEVEL=35 +PATCH_LEVEL=36 MY_PATCH_LEVEL= diff --git a/scm/define-markup-commands.scm b/scm/define-markup-commands.scm index e94ddd68ef..046dee06f6 100644 --- a/scm/define-markup-commands.scm +++ b/scm/define-markup-commands.scm @@ -163,8 +163,8 @@ some punctuation. It doesn't have any letters. " (def-markup-command (dynamic paper props arg) (markup?) "Use the dynamic font. This font only contains @b{s}, @b{f}, @b{m}, -@b{z}, @b{p}, and @b{r}. When producing phrases, like ``più @b{f}'', the -normal words (like ``più'') should be done in a different font. The +@b{z}, @b{p}, and @b{r}. When producing phrases, like ``pi@`{u} @b{f}'', the +normal words (like ``pi@`{u}'') should be done in a different font. The recommend font for this is bold and italic" (interpret-markup paper (prepend-alist-chain 'font-encoding 'dynamic props) arg)) -- 2.39.2