X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fintroduction.itely;h=a27db04c1015b40c4f191221812928c382a1aa1d;hb=38d7d319eabc906e82fb42002678c6d42a23b6f7;hp=7a7db27863079c2ec89be25231ace6939f149efc;hpb=222b0bff12be16c385df77f4cfa89101aafeece7;p=lilypond.git diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 7a7db27863..a27db04c10 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -7,7 +7,7 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.51" +@c \version "2.12.0" @node Introduction @chapter Introduction @@ -16,8 +16,8 @@ This chapter introduces readers to LilyPond and the documentation. @menu -* Background:: -* About the documentation:: +* Background:: +* About the documentation:: @end menu @@ -28,17 +28,23 @@ This section covers the overall goals and architecture of LilyPond. @menu -* Engraving:: -* Automated engraving:: -* What symbols to engrave?:: -* Music representation:: -* Example applications:: +* Engraving:: +* Automated engraving:: +* What symbols to engrave?:: +* Music representation:: +* Example applications:: @end menu @node Engraving @unnumberedsubsec Engraving +@cindex engraving +@cindex typography, music +@cindex music typography +@cindex plate engraving +@cindex music engraving + The art of music typography is called @emph{(plate) engraving}. The term derives from the traditional process of music printing. Just a few decades ago, sheet music was made by cutting and @@ -188,6 +194,7 @@ music = { @cindex regular rhythms @cindex regular spacing +@cindex spacing, regular Each bar in the fragment only uses notes that are played in a constant rhythm. The spacing should reflect that. Unfortunately, @@ -201,7 +208,6 @@ of the notes. The upper two measures are printed with this correction, the lower two measures without, forming down-stem/@/up-stem clumps of notes. -@cindex typography Musicians are usually more absorbed with performing than with studying the looks of a piece of music, so nitpicking about @@ -241,6 +247,9 @@ to see and love to play from. @node Automated engraving @unnumberedsubsec Automated engraving +@cindex engraving, automated +@cindex automated engraving + How do we go about implementing typography? If craftsmen need over ten years to become true masters, how could we simple hackers ever write a program to take over their jobs? @@ -278,6 +287,8 @@ music notation works. @end itemize +@cindex Scheme programming language + These problems have been addressed by integrating an interpreter for the Scheme programming language and rewriting parts of LilyPond in Scheme. The current formatting architecture is built @@ -304,6 +315,10 @@ chord has all directions up (right). } @end lilypond +@cindex score formatting +@cindex formatting a score +@cindex formatting rules + @noindent The process of formatting a score consists of reading and writing the variables of graphical objects. Some variables have a preset @@ -346,34 +361,33 @@ changed during the music fragment. (pos (ly:grob-property grob 'staff-position))) (if (memq 'note-head-interface interfaces) (begin - (ly:grob-set-property! grob 'stencil ly:text-interface::print) - (ly:grob-set-property! grob 'font-family 'roman) - (ly:grob-set-property! grob 'text - (make-raise-markup -0.5 - (case pos - ((-5) (make-simple-markup "m")) - ((-3) (make-simple-markup "c ")) - ((-2) (make-smaller-markup (make-bold-markup "2"))) - (else (make-simple-markup "bla"))))))))) + (ly:grob-set-property! grob 'stencil + (grob-interpret-markup grob + (make-lower-markup 0.5 + (case pos + ((-5) "m") + ((-3) "c ") + ((-2) (make-smaller-markup (make-bold-markup "2"))) + (else "bla"))))))))) \new Voice \relative c' { - \stemUp - \set autoBeaming = ##f - \time 2/4 - 4 - \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil - \once \override NoteHead #'font-size = #-7 - \once \override NoteHead #'font-family = #'sans - \once \override NoteHead #'font-series = #'bold - - \once \override NoteHead #'style = #'cross - - \applyOutput #'Voice #mc-squared - - << - { d8[ es-( fis^^ g] fis2-) } - \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 } - >> + \stemUp + \set autoBeaming = ##f + \time 2/4 + 4 + \once \override NoteHead #'stencil = #ly:note-head::brew-ez-stencil + \once \override NoteHead #'font-size = #-7 + \once \override NoteHead #'font-family = #'sans + \once \override NoteHead #'font-series = #'bold + 4 + \once \override NoteHead #'style = #'cross + 4 + \applyOutput #'Voice #mc-squared + 4 + << + { d8[ es-( fis^^ g] fis2-) } + \repeat unfold 5 { \applyOutput #'Voice #mc-squared s8 } + >> } @end lilypond @@ -383,6 +397,8 @@ changed during the music fragment. @cindex engraving @cindex typography +@cindex engraver +@cindex plug-in The formatting process decides where to place symbols. However, this can only be done once it is decided @emph{what} symbols @@ -539,6 +555,10 @@ signature, and key signature, we get a complete piece of notation. \score { \topVoice } @end lilypond +@cindex polyphony +@cindex engraving multiple voices +@cindex contexts + This system works well for monophonic music, but what about polyphony? In polyphonic notation, many voices can share a staff. @@ -557,10 +577,11 @@ context contains more than one Voice context. Similarly, multiple Staff contexts can be put into a single Score context. The Score context is the top level notation context. -@seealso +@seealso Internals Reference: @rinternals{Contexts}. + @lilypond[quote,ragged-right] \include "engraver-example.ily" \score { @@ -575,6 +596,9 @@ Internals Reference: @rinternals{Contexts}. @node Music representation @unnumberedsubsec Music representation +@cindex syntax +@cindex recursive structures + Ideally, the input format for any high-level formatting system is an abstract description of the content. In this case, that would be the music itself. This poses a formidable problem: how can we @@ -671,6 +695,9 @@ the source code. @node Example applications @unnumberedsubsec Example applications +@cindex simple examples +@cindex examples, simple + We have written LilyPond as an experiment of how to condense the art of music engraving into a computer program. Thanks to all that hard work, the program can now be used to perform useful @@ -689,8 +716,12 @@ By adding chord names and lyrics we obtain a lead sheet. @lilypond[quote,ragged-right] << \chords { c2 c f2 c } - \new Staff \relative c' { \time 2/4 c4 c g'4 g a4 a g2 } - \new Lyrics \lyricmode { twin4 kle twin kle lit tle star2 } + \new Staff + \relative c' { + \time 2/4 + c4 c g' g a a g2 + } + \addlyrics { twin -- kle twin -- kle lit -- tle star } >> @end lilypond @@ -712,7 +743,7 @@ following example combines some more exotic constructs. << { \revert Stem #'direction \change Staff = down - \set subdivideBeams = ##t + \set subdivideBeams = ##t g16.[ \change Staff = up c'''32 @@ -743,7 +774,7 @@ following example combines some more exotic constructs. \override Beam #'thickness = #0.3 \override Stem #'thickness = #4.0 g'16[ b16 fis16 g16] - << \makeClusters { + << \makeClusters { as16 @@ -788,6 +819,13 @@ makes it easy to mix music and text in documents. This section explains the different portions of the documentation. +@cindex Learning Manual +@cindex Music Glossary +@cindex Notation Reference +@cindex Application Usage +@cindex Snippet List +@cindex Internals Reference + @c leave these lines wrapping around. It's some texinfo 4.12 thing. -gp @c This is actually a limitation of texi2html. -jm @menu @@ -804,6 +842,8 @@ This section explains the different portions of the documentation. @node About the Learning Manual @unnumberedsubsec About the Learning Manual +@cindex Learning Manual + This book explains how to begin learning LilyPond, as well as explaining some key concepts in easy terms. You should read these chapters in a linear fashion. @@ -863,6 +903,7 @@ all. @node About the Music Glossary @unnumberedsubsec About the Music Glossary +@cindex Music Glossary @cindex idiom @cindex jargon @cindex terminology @@ -879,6 +920,11 @@ it is highly advisable to consult the glossary. @node About the Notation Reference @unnumberedsubsec About the Notation Reference +@cindex Notation Reference +@cindex appendices +@cindex reference charts +@cindex charts, reference + This book explains all the LilyPond commands which produce notation. It assumes that readers are familiar with the concepts in the Learning Manual. @@ -951,6 +997,9 @@ a complete index. @node About the Application Usage @unnumberedsubsec About the Application Usage +@cindex Application Usage +@cindex integrating LilyPond with other programs + This book explains how to execute the programs and how to integrate LilyPond notation with other programs. @@ -992,6 +1041,8 @@ formats to the @code{.ly} format. @cindex snippets @cindex LSR +@cindex Snippet List +@cindex LilyPond Snippet Repository @rlsrnamed{Top,LilyPond Snippet List}: this shows a selected set of LilyPond snippets from the @@ -1011,6 +1062,8 @@ also linked from the @strong{See also} portion. @node About the Internals Reference @unnumberedsubsec About the Internals Reference +@cindex Internals Reference + @rinternalsnamed{Top,Internals Reference}: this is a set of heavily cross linked HTML pages which document the nitty-gritty details of each and every LilyPond class, object, and function.