2003-04-11 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+ * Documentation/user/lilypond.tely: remove abbreviations (n't, 's)
+
* lily/multi-measure-rest-engraver.cc (stop_translation_timestep):
add staff support.
@node Default contexts
@subsection Default contexts
-Most music expressions don't need an explicit @code{\context}
+Most music expressions do not need an explicit @code{\context}
declaration: they inherit the notation context from their parent. Each
note is a music expression, and as you can see in the following example,
only the sequential music enclosing the three notes has an explicit context.
(for example) and thus take effect in all @internalsref{Voice} contexts.
@cindex @code{Current}
-If you don't wish to specify the name of the context in the
+If you do not wish to specify the name of the context in the
@code{\property}-expression itself, you can refer to the abstract context
name, @code{Current}. The @code{Current} context is the latest
used context. This will typically mean the @internalsref{Thread}
Some engraver types need to be at the end of the list; this
insures they stay there even if a user adds or removes engravers.
-End-users generally don't need this command.
+End-users generally do not need this command.
@item @code{\accepts} @var{contextname}:
Add @var{contextname} to the list of contexts this context can
@item @code{\name} @var{contextname}:
This sets the type name of the context, e.g. @internalsref{Staff},
-@internalsref{Voice}. If the name is not specified, the translator won't do
+@internalsref{Voice}. If the name is not specified, the translator will not do
anything.
@end itemize
music is produced without any further intervention. For example,
something like this:
-@lilypond[fragment,verbatim, relative 1, intertext="produces this"]
+@lilypond[fragment,verbatim, relative 1, intertext="produces this
+
+"]
\key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
@end lilypond
effort to learn the codes and the program you will find that it is
easier than it seems. Entering music can be done quickly, and you
never have to remember how you made the program do something
-complicated: it's all in the input code, and you only have to read the
-file to see how it works. Moreover, when you use LilyPond, you are
+complicated: it is all in the input code, and you only have to read
+the file to see how it works. Moreover, when you use LilyPond, you are
rewarded with very nicely looking output.
In this chapter, we will explain the reasoning behind this unusual
achieve computing tasks, so our computerized music engraving
experiment took on the form of a compiler.
+
+@ignore
@cindex free software
@cindex sharing software
that bandwagon, and released LilyPond as free software. That is the
reason that you can get LilyPond at no cost and without any strings
attached.
+@end ignore
@node Music engraving
corrections was cumbersome, so engraving had to be done correctly in
one go. As you can imagine this was a highly specialized skill, much
more so than the traditional process of printing books.
-
@cindex craftsmanship
@cindex master
-
-The following fact illustrates that. In the traditional German
-craftsmanship six years of full-time training, more than any other
-craft, were required before a student could call himself a master of
-the art. After that many more years of practical experience were
-needed to become an established music engraver. Even today, with the
-use of high-speed computers and advanced software, music requires lots
-of manual fine tuning before it acceptable to be published.
+In the traditional German craftsmanship six years of full-time
+training, more than any other craft, were required before a student
+could call himself a master of the art. After that many more years of
+practical experience were needed to become an established music
+engraver. Even today, with the use of high-speed computers and
+advanced software, music requires lots of manual fine tuning before it
+acceptable to be published.
When we wanted to write a computer program to do create music
typography, we encountered the first problem: there were no sets of
musical symbols available: either they were not available freely, or
-they didn't look well to our taste. Not let down, we decided to try
+they did not look well to our taste. Not let down, we decided to try
font design ourselves. We created a font of musical symbols, relying
-on nice printouts of hand-engraved music. It was a good decision to
-design our own font. The experience helped develop a typographical
-taste, and it made us appreciate subtle design details. Without that
-experience, we would not have realized how ugly the fonts were that we
-admired at first.
+on nice printouts of hand-engraved music. The experience helped
+develop a typographical taste, and it made us appreciate subtle design
+details. Without that experience, we would not have realized how ugly
+the fonts were that we admired at first.
@lilypond[noindent]
One of the big questions when making programs, is what kind of input
the program should expect. Many music notation programs offer a
graphical interface that shows notation, and allow you to enter the
-music by placing notes on a staff. Although this is a obvious way to
-design a program, from our point of view, it is cheating. After all,
-the core message of a piece of music notation simply is the music
-itself. If you start by offering notation to the user, you have
-already skipped one conversion, even if it is implicit. If we want to
-generate music notation from something else, then the obvious
-candidate for the source is the music itself.
+music by placing notes on a staff. From our point of view, this design
+is a form of cheating. After all, the core message of a piece of music
+notation simply is the music itself. If you start by offering notation
+to the user, you have already skipped one conversion, even if it is
+implicit. If we want to generate music notation from something else,
+then the obvious candidate for the source is the music itself.
On paper this theory sounds very good. In practice, it opens a can of
worms. What really @emph{is} music? Many philosophical treatises must
-have been written on the subject. Even if you are more practically
+have been written on the subject. Fortunately, we have a concrete
+application, so we do not run the risk of losing ourselves in
+philosophical arguments over the essence of music. We want to produce
+a printed score from a music representation, so this gives us a nice
+guide for designing a format: we need a format containing mainly
+musical elements, such as pitch and duration, but also enough
+information to print a score. Our users have to key in the music into
+the file directly, so the input format should have a friendly
+syntax. Finally, we as programmers and scientists want a clean formal
+definition. After all, producing music notation is a difficult
+problem, and in the scientific world, problems can only be solved if
+they are well-specified. Moreover, formally defined formats are easier
+to write programs for.
+
+@ignore
+Even if you are more practically
inclined, you will notice that there exist an enormous number of ways
to represent music in a computer, and they are much more incompatible
than the formats for word processors and spreadsheets. Anyone who has
tried to exchange data files from between different notation programs
can attest to this.
-@cindex music representation
-@cindex music expressions
-@cindex input format
-
This problem is caused by the two-dimensional nature of music: in
polyphonic music, notes have time and pitch as their two coordinates,
and they often are related in both directions. Computer files on the
flatten this two-dimensional information breaking either timing or
pitch relations, and there is no universal agreement on how to do
this.
+@end ignore
+
+
+@cindex music representation
+@cindex music expressions
+@cindex input format
-Fortunately, we have a concrete application, so we don't run the risk
-of losing ourselves in philosophical arguments over the essence of
-music. We want to produce a printed score from a music
-representation, so this gives us a nice guide for designing a format:
-we need a format containing mainly musical elements, such as pitch and
-duration, but also enough information to print a score. Our users
-have to key in the music into the file directly, so the input format
-should have a friendly syntax. Finally, we as programmers and
-scientists want a clean formal definition. After all, producing music
-notation is a difficult problem, and in the scientific world, problems
-can only be solved if they are well-specified. Moreover, formally
-defined formats are easier to write programs for.
These ideas shaped our music representation: it is a compact format
that can easily be typed by hand. It complex musical constructs from
to lilypond, then you should start reading the tutorial, and
experiment for yourself. If you already have some experience, then
you can simply use the manual as reference: there is an extensive
-index@footnote{If you are looking for something, and you can't find it
+index@footnote{If you are looking for something, and you cannot find it
by using the index, that is considered a bug. In that case, please
file a bug report}, but the document is also available in One Big Page,
@c should have hyperlink?
@end itemize
You can send the report to @email{bug-lilypond@@gnu.org}. This is a
-mailinglist, but you don't have to be subscribed to it to post.
+mailinglist, but you do not have to be subscribed to it to post.
@node Website
@section Website
@cindex PDF
@cindex Scalable fonts
- If you use lilypond-book or your own wrapper files, don't use
-@code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget
+ If you use lilypond-book or your own wrapper files, do not use
+@code{\usepackage[[T1]@{fontenc@}} in the file header but do not forget
@code{\usepackage[latin1]@{inputenc@}} if you use any other
non-anglosaxian characters.
This option affects LilyPond output, not the text layout.
@item notime
-Don't print time signature.
+Do not print time signature.
@item fragment
@itemx nofragment
Prepend @var{pref} before each @option{-M} dependency.
@item @option{-n}, @option{--no-lily}
-Don't run LilyPond, but do generate the @code{.ly} files.
+Do not run LilyPond, but do generate the @code{.ly} files.
@item @option{--no-music}
Strip all LilyPond blocks from the file.
@item @option{--no-pictures}
-Don't generate pictures when processing Texinfo.
+Do not generate pictures when processing Texinfo.
@item @option{--read-lys}
-Don't write ly files. This way you can do
+Do not write ly files. This way you can do
@example
lilypond-book file.tely
@end ignore
+@ignore
+
+HINTS FOR STYLE
+
+* don't refer to LilyPond in the text. The reader knows what the
+manual is about
+
+* don't explicitly refer to the reader/user. There is no one else
+besides the reader and the writer.
+
+* don't use abbreviations (don't, won't, etc.)
+
+
+@end ignore
@ifhtml
This document is also available in @uref{../lilypond.ps.gz,gzipped
@end macro
@ignore
-We don't use refs for Info:
+We do not use refs for Info:
@w{@ar{}\word\}@c vs:
@w{@ar{}@pxref{\word\}}@c
In some ways, developing a computer program is like learning to play
an instrument. In the beginning, discovering how it works is fun, and
-the things you can't do are challenging. After the initial excitement,
+the things you cannot do are challenging. After the initial excitement,
you have to practice and practice. Scales and studies can be dull, and
-if you aren't motivated by others---teachers, conductors or
+if you are not motivated by others---teachers, conductors or
audience---it is very tempting to give up. You continue, and gradually
playing becomes a part of your life. Some days it comes naturally, and
-it's wonderful, and on some days it just doesn't work, but you keep
+it is wonderful, and on some days it just does not work, but you keep
playing, day after day.
Like making music, working on LilyPond is can be dull work, and on
bugs. Nevertheless, it has become a part of our life, and we keep
doing it. Probably the most important motivation is that our program
actually does something useful for people. When we browse around the
-net we find many people that use LilyPond, and use it to produce
-impressive pieces of sheet music. Seeing that still feels unreal, but
-in a very pleasant way.
+net we find many people that use LilyPond, and produce impressive
+pieces of sheet music. Seeing that still feels unreal, but in a very
+pleasant way.
Our users not only give us good vibes by using our program, many of
them also help us by giving suggestions and sending bugreports. So
was truly a masterclass, and Heinz Stolba and James Ingram for
teaching us there.
-Playing and printing music is more than nice analogy: programming
+Playing and printing music is more than nice analogy. Programming
together is a lot of fun, and helping people is deeply satisfying, but
ultimately, working on LilyPond is a way to express our deep love for
music. May it help you create lots of beautiful music!
}
@end lilypond
-The skip command is merely an empty musical placeholder. It doesn't
+The skip command is merely an empty musical placeholder. It does not
produce any output, not even transparent output.
In Note, Chord, and Lyrics mode, durations are designated by numbers
and dots: durations are entered as their reciprocal values. For example,
-a quarter note is entered using a @code{4} (since it's a 1/4 note), while
-a half note is entered using a @code{2} (since it's a 1/2 note). For notes
+a quarter note is entered using a @code{4} (since it is a 1/4 note), while
+a half note is entered using a @code{2} (since it is a 1/2 note). For notes
longer than a whole you must use identifiers.
-@c FIXME: what's an identifier? I don't think it's been introduced yet.
+@c FIXME: what's an identifier? I do not think it's been introduced yet.
@c and if it has, I obviously skipped that part. - Graham
@example
You can alter the length of duration by a fraction @var{N/M}
appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
-won't affect the appearance of the notes or rests produced.
+will not affect the appearance of the notes or rests produced.
@lilypond[fragment,verbatim]
a'2*2 b'4*2 a'8*4 a'4*3/2 gis'4*3/2 a'4*3/2 a'4
@node Automatic note splitting
@subsection Automatic note splitting
-@c FIXME: This subsection doesn't belong in @ref{Note entry}.
+@c FIXME: This subsection does not belong in @ref{Note entry}.
LilyPond can automatically converting long notes to tied notes. This
is done by replacing the @code{Note_heads_engraver} by the
Whenever a bar check is encountered during interpretation, a warning
-message is issued if it doesn't fall at a measure boundary. This can
+message is issued if it does not fall at a measure boundary. This can
help you find errors in the input. Depending on the value of
@code{barCheckSynchronize}, the beginning of the measure will be
relocated, so this can also be used to shorten measures.
In which context is the rule applied. I.e. if context is
@internalsref{Score} then all staves share accidentals, and if
context is @internalsref{Staff} then all voices in the same
- staff share accidentals, but staves don't - like normally.
+ staff share accidentals, but staves do not - like normally.
@item Octavation:
Whether the accidental changes all octaves or only the current
octave.
It is possible to use @TeX{} commands in the strings, but this should be
avoided because it makes it impossible for LilyPond to compute the
exact length of the string, which may lead to collisions. Also, @TeX{}
-commands won't work with direct PostScript output.
+commands will not work with direct PostScript output.
@c (see @ref{PostScript output}).
Text scripts are created in form of @internalsref{TextScript} objects, in
use those default values unless you specify otherwise inside the
@code{\grace} section. For example, if you specify \slurUp
@emph{before} your @code{\grace} section, a slur which starts inside
-the @code{\grace} won't be forced up, even if the slur ends outside
+the @code{\grace} will not be forced up, even if the slur ends outside
of the @code{\grace}. Note the difference between the first and
second bars in this example:
@end lilypond
-If you don't give enough alternatives for all of the repeats, then
+If you do not give enough alternatives for all of the repeats, then
the first alternative is assumed to be repeated often enough to equal
the specified number of repeats.
@end lilypond
@end table
-If you don't like any of the predefined lists you can define your own
+If you do not like any of the predefined lists you can define your own
list at the top of your file:
@lilypond[singleline, verbatim]
@subsubsection Percussion staves with normal staves
When you include @file{drumpitch-init.ly} then the default pitches
are overridden so that you after the inclusion cannot use the common
-dutch pitch names anymore. Hence you might wan't to reinclude
+dutch pitch names anymore. Hence you might want to reinclude
@file{nederlands.ly} after the drum-pattern-definitions:
@lilypond[singleline,verbatim]
\include "drumpitch-init.ly"
@table @code
@item \dynamic
This changes to the font used for dynamic signs. Note that this font
-doesn't contain all characters of the alphabet.
+does not contain all characters of the alphabet.
@item \number
This changes to the font used for time signatures. It only contains
numbers and a few punctuation marks.
\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
@end lilypond
-If you don't specify a @rglos{duration}, the previous one is used:
+If you do not specify a @rglos{duration}, the previous one is used:
@example
a4 a a2 a
@end quotation
@separate
-@c Tim wants to move this quotes example just before the: quotes-don't-work
+@c Tim wants to move this quotes example just before the: quotes-do not-work
@c score, but we'd need to remove quotes from the other two (key and
@c tie) examples...
@c accidentals...
There are some interesting points to note in this example.
-Accidentals (sharps and flats) don't have to be marked explicitly: you
+Accidentals (sharps and flats) do not have to be marked explicitly: you
just enter the note name, and LilyPond determines whether or not to
print an accidental. Bar lines and beams are drawn automatically.
-LilyPond calculates line breaks for you; it doesn't matter where you
+LilyPond calculates line breaks for you; it does not matter where you
make new lines in the source file. Finally, the order of time, key and
clef changes is not relevant: lilypond will use standard notation
conventions for ordering these items.
The solution is to use ``relative octave'' mode. In practice, this is
the most convenient way to copy existing music. To use relative mode,
add @code{\relative} before the piece of music. You must also give a
-note from which relative starts, in this case @code{c''}. If you don't
-use octavation quotes (ie don't add ' or , after a note), relative mode
+note from which relative starts, in this case @code{c''}. If you do not
+use octavation quotes (ie do not add ' or , after a note), relative mode
chooses the note that is closest to the previous one. Since most music
has small intervals, you can write quite a lot in relative mode without
using octavation quotes.
-@c don't use commas or quotes in this sentence
+@c do not use commas or quotes in this sentence
For example: @code{c f} goes up; @code{c g} goes down:
@quotation
You can make larger intervals by adding octavation quotes. Note that
quotes or commas do not determine the absolute height of a note;
the height of a note is relative to the previous one.
-@c don't use commas or quotes in this sentence
+@c do not use commas or quotes in this sentence
For example: @code{c f,} goes down; @code{f, f} are both the same;
@code{c' c} are the same; and @code{c g'} goes up:
@c lousy example
@c ? --hwn
@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
-@c chromatic thing pasted in front. (admittedly the original doesn't
-@c have a phrasing slur. The problem is that we don't want the slur
+@c chromatic thing pasted in front. (admittedly the original does not
+@c have a phrasing slur. The problem is that we do not want the slur
@c and the Phrasing slur to collide. We're trying to make a good
@c impression here.
@end quotation
@separate
-Beams are drawn automatically, but if you don't like the choices, you
+Beams are drawn automatically, but if you do not like the choices, you
can enter beams by hand. Mark the first note to be beamed with
@code{[} and the last one with @code{]}:
@quotation
@end quotation
In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves. It doesn't matter what names you give, as long
+given to the staves. It does not matter what names you give, as long
as each staff has a different name. If you give them the same name,
LilyPond will assume that you only want one staff, and will but both
pieces of music on the same staff.
@ignore
When you want to combine chords with slurs and dynamics, technical
detail crops up: you have type these commands next to the notes, which
-means that they have to be inside the @code{< >}. Don't get confused
+means that they have to be inside the @code{< >}. Do Not get confused
by the chord @code{< >} and the dynamic @code{\< \>}!
@end ignore
context'). These objects only exist while LilyPond is executing.
When LilyPond interprets music, it will create a Staff context.
-We don't want that default here, because we want lyric. The
+We do not want that default here, because we want lyric. The
command
@example
\context Lyrics
explicitly creates an interpretation context of
@code{Lyrics} type to interpret the song text that we entered.
-The melody of the song doesn't offer anything new:
+The melody of the song does not offer anything new:
@example
\notes \relative c' @{
\time 7/4
the @code{%} sign in the previous line were removed, you could see
that mechanism in action.
-We don't want that default here, because we want chord names. The
+We do not want that default here, because we want chord names. The
command above explicitly creates an interpretation context of
@code{ChordNames} type to interpret the music @code{\accompaniment}.
@end example
A paper block at top level (i.e. not in a @code{\score} block) sets the
-default page layout. The following @code{\score} blocks don't have
+default page layout. The following @code{\score} blocks do not have
@code{\paper} sections, so the settings of this block are used.
The variable @code{linewidth} normally sets the length of the systems
In previous examples, most notes were specified in relative octaves
(i.e. each note was put in the octave that is closest to its
predecessor). Besides relative, there is also absolute octave
-specification, which you get when you don't include @code{\relative} in
+specification, which you get when you do not include @code{\relative} in
your input file. In this input mode, the middle C is denoted by
@code{c'}. Going down, you get @code{c} @code{c,} @code{c,,} etc.
Going up, you get @code{c''} @code{c'''} etc.
@end example
@code{s} is a spacer rest. It does not print anything, but it does have
the duration of a rest. It is useful for filling up voices that
-temporarily don't play. In this case, the viola doesn't come until one
+temporarily do not play. In this case, the viola does not come until one
and a half measure later.
@separate
<
@end example
At this point, the homophonic music splits into two rhythmically
-different parts. We can't use a sequence of chords to enter this, so
+different parts. We cannot use a sequence of chords to enter this, so
we make a "chord of sequences" to do it. We start with the upper
voice, which continues with upward stems:
@separate
object in the current @code{Voice}. The variable @code{attachment} is
set to the pair of symbols @code{'(stem . stem)}.
-Although this fixes the slur, it isn't very helpful for fine tuning in
+Although this fixes the slur, it is not very helpful for fine tuning in
general: the lilypond back-end supports approximately 240 variables
like @code{attachment}, each with their own meaning and own type
(eg. number, symbol, list, etc). Besides slur, LilyPond has 80
Normally one would specify all dynamics in the same voice, so that
dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
-in this case, we don't want the decrescendo to be aligned with the
+in this case, we do not want the decrescendo to be aligned with the
piano sign. We achieve this by putting the dynamic markings in different
voices. The crescendo should be above the upper staff. This can be
forced by using the precooked command
This orchestral score example consists of three input files. In the
first file, @file{os-music.ly}, we define the music for all
instruments. This file will be used for producing the score and
-the separate parts, but the file doesn't produce any sheet music
+the separate parts, but the file does not produce any sheet music
itself. Other files reference this file by doing @code{\include
"os-music.ly"}.
@example
\notes \key bes \major
@end example
-Since the horn is transposing, it's in a different key.
+Since the horn is transposing, it is in a different key.
@separate
@example
\flautoII
@end example
In this individual part the second flute has a whole staff for itself,
-so we don't want to force stem or tie directions.
+so we do not want to force stem or tie directions.
@separate
@example
notation. This program is fully described in the chapter
@ref{Integrating text and music with lilypond-book}. Here we show a
small example. Since the example also contains explanatory text, we
-won't comment on the contents.
+will not comment on the contents.
@example
\documentclass[a4paper]@{article@}
@end example
Notice the @code{outdir} option to lilypond-book. Running lilypond-book
-and running latex creates a lot of temporary files, and you wouldn't want
+and running latex creates a lot of temporary files, and you would not want
those to clutter up your working directory. Hence, we have them created
in a separate subdirectory.
own input files. Come back to the reference manual for more information
if you get stuck!
-Don't forget to check out the
+Do not forget to check out the
@ifhtml
@uref{../../../../input/template/out-www/template.html,templates},
@uref{../../../../input/test/out-www/test.html,examples} and
projects / lilypond.git / commitdiff