From: Graham Percival Date: Thu, 9 Jul 2009 03:09:43 +0000 (-0700) Subject: Doc: move essay into its own manual. X-Git-Tag: release/2.13.4-1~372^2~4 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=067ab33ca74bba0d88e6badf6bfda63240d1dc3d;p=lilypond.git Doc: move essay into its own manual. --- diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 03a6a8a909..e8d3665d33 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -2,7 +2,7 @@ depth = .. NAME = documentation LANGS = $(shell $(PYTHON) $(top-src-dir)/python/langdefs.py) -SUBDIRS=devel user bibliography pictures topdocs misc po $(LANGS) +SUBDIRS=devel user essay bibliography pictures topdocs misc po $(LANGS) STEPMAKE_TEMPLATES=documentation texinfo tex LOCALSTEPMAKE_TEMPLATES=lilypond ly LILYPOND_BOOK_FLAGS=--extra-options '-e "(ly:set-option (quote internal-type-checking) \#t)"' diff --git a/Documentation/essay/GNUmakefile b/Documentation/essay/GNUmakefile new file mode 100644 index 0000000000..8d78ffe561 --- /dev/null +++ b/Documentation/essay/GNUmakefile @@ -0,0 +1,145 @@ +depth=../.. + +LATEX_FILES =$(call src-wildcard,*.latex) + + +EXTRA_DIST_FILES = $(LATEX_FILES) $(IMAGES) $(EPS_ILLUSTRATIONS) + +IMAGES=$(call src-wildcard,*.png) +EPS_ILLUSTRATIONS= +PDF_ILLUSTRATIONS= + +OUT_PDF_IMAGES=$(IMAGES:%.png=$(outdir)/%.pdf) $(addprefix $(outdir)/,$(PDF_ILLUSTRATIONS)) + +OUT_PNG_IMAGES=$(OUT_PDF_IMAGES:%.pdf=%.png) + +#OUT_MASTER_TEXI_FILES = $(outdir)/lilypond-internals.texi +OUT_TEXI_FILES=$(ITEXI_FILES:%.itexi=$(outdir)/%.texi)\ + $(ITELY_FILES:%.itely=$(outdir)/%.texi) + +HTML_FILES = $(TELY_FILES:%.tely=$(outdir)/%-big-page.html)\ + +# $(outdir)/lilypond-internals-big-page.html + +# todo: add latex. +PDF_FILES = $(TELY_FILES:%.tely=$(outdir)/%.pdf)\ + +# $(outdir)/lilypond-internals.pdf + +MAIN_INFO_DOC = lilypond-essay +INFO_DOCS = lilypond-essay +INFO_FILES = $(INFO_DOCS:%=$(outdir)/%.info) + +TEXI2PDF_FLAGS = \ + -I $(outdir) \ + -I $(top-src-dir)/Documentation/essay \ + -I $(top-build-dir)/Documentation/essay/$(outconfbase) + +ifeq ($(out),www) +INFO_IMAGES_DIR = lilypond +DEST_INFO_IMAGES_SUBDIR = Documentation/essay +endif + +STEPMAKE_TEMPLATES=texinfo documentation +#OMF_FILES += $(outdir)/lilypond-internals.html.omf + +LOCALSTEPMAKE_TEMPLATES=lilypond ly + +include $(depth)/make/stepmake.make + +default: + +info: $(INFO_FILES) + @echo export LILYPOND_DATADIR=$(LILYPOND_DATADIR) + @echo export PYTHONPATH=$(PYTHONPATH) + +xml: $(outdir)/lilypond-essay/lilypond.xml +#xml: $(outdir)/lilypond/lilypond.xml $(outdir)/lilypond-internals/lilypond-internals.xml + + +local-clean: + rm -f $(INFO_IMAGES_DIR) + +local-help: extra-local-help + +extra-local-help: + @echo -e "\ + info update info pages\n\ + xml update Docbook xml documentation\n\ +" + +# +# Split manuals in HTML +# +$(outdir)/lilypond-essay/index.html: $(OUT_PNG_IMAGES) $(OUT_EPS_IMAGES) +#$(outdir)/lilypond-learning/index.html: $(OUT_PNG_IMAGES) $(OUT_EPS_IMAGES) + + +# +# Manuals in one big HTML page +# +$(outdir)/lilypond-essay-big-page.html: $(OUT_PNG_IMAGES) +#$(outdir)/lilypond-learning-big-page.html: $(OUT_PNG_IMAGES) + +$(outdir)/lilypond.xml: $(outdir)/lilypond-essay.texi + mkdir -p $(dir $@) + $(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$@ --docbook $< + +#$(outdir)/lilypond-internals/lilypond-internals.xml: $(outdir)/lilypond-internals.texi +# mkdir -p $(dir $@) +# $(MAKEINFO) -I$(src-dir) -I$(outdir) --output=$(outdir)/lilypond-internals --docbook $< + +$(outdir)/lilypond-essay.pdf: $(OUT_PDF_IMAGES) + +$(outdir)/%.png: %.png + convert -depth 8 -geometry 50x50% $< $@ + +$(outdir)/%.png: %.eps + gs -dTextAlphaBits=4 -dGraphicsAlphaBits=4 -q -sOutputFile=$@ -sDEVICE=png16m -dEPSCrop -dNOPAUSE -f $< -c quit + +$(outdir)/%.pdf: %.png + convert -depth 8 $< $@ + +$(outdir)/%.pdf: %.eps + gs -dAutoRotatePages=/None -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=$@ -dEPSCrop -c .setpdfwrite -f $< + + +DEEP_HTML_FILES =\ + $(outdir)/lilypond-essay/index.html\ + +# $(outdir)/lilypond/index.html\ +# $(outdir)/lilypond-internals/index.html\ +# $(outdir)/music-glossary/index.html\ +# $(outdir)/lilypond-program/index.html\ +# $(outdir)/lilypond-learning/index.html + +# Symlinks to refer to external source documents from split and non-split HTML +source-links = $(outdir)/source $(outdir)/lilypond/source $(outdir)/music-glossary/source \ + $(outdir)/lilypond-program/source $(outdir)/lilypond-learning/source $(outdir)/lilypond-internals/source + + +$(outdir)/source: + @rm -f $(@) + ln -sf $(depth) $(@) + +$(outdir)/%/source: + @rm -f $(@) + mkdir -p $(dir $@) + ln -sf $(depth)/.. $(@) + +ifeq ($(out),www) +local-WWW-1: $(MASTER_TEXI_FILES) $(PDF_FILES) info + +local-WWW-2: $(HTML_FILES) $(DEEP_HTML_FILES) $(source-links) +endif + +$(outdir)/%.bib: %.bib + ln -f $< $@ + +# lilypond.texi deps +$(top-build-dir)/mf/$(outconfbase)/feta16list.ly: + $(MAKE) -C $(top-src-dir)/mf + +$(outdir)/lilypond-essay.texi: $(ITELY_FILES) $(ITEXI_FILES) + +.SECONDARY: diff --git a/Documentation/essay/baer-flat-bw.png b/Documentation/essay/baer-flat-bw.png new file mode 100644 index 0000000000..bb25bd1903 Binary files /dev/null and b/Documentation/essay/baer-flat-bw.png differ diff --git a/Documentation/essay/baer-flat-gray.png b/Documentation/essay/baer-flat-gray.png new file mode 100644 index 0000000000..08cd338380 Binary files /dev/null and b/Documentation/essay/baer-flat-gray.png differ diff --git a/Documentation/essay/fdl.itexi b/Documentation/essay/fdl.itexi new file mode 100644 index 0000000000..158e5c6c30 --- /dev/null +++ b/Documentation/essay/fdl.itexi @@ -0,0 +1,403 @@ + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.1, March 2000 + +@display +Copyright @copyright{} 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document @dfn{free} in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of @q{copyleft}, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The @q{Document}, below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as @q{you}. + +A @q{Modified Version} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A @q{Secondary Section} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The @q{Invariant Sections} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The @q{Cover Texts} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A @q{Transparent} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not @q{Transparent} is called @q{Opaque}. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, +@acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed +for human modification. Opaque formats include PostScript, +@acronym{PDF}, proprietary formats that can be read and edited only by +proprietary word processors, @acronym{SGML} or @acronym{XML} for which +the @acronym{DTD} and/or processing tools are not generally available, +and the machine-generated @acronym{HTML} produced by some word +processors for output purposes only. + +The @q{Title Page} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, @q{Title Page} means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has less than five). + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section entitled @q{History}, and its title, and add to +it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section entitled @q{History} in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the @q{History} section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +In any section entitled @q{Acknowledgments} or @q{Dedications}, +preserve the section's title, and preserve in the section all the +substance and tone of each of the contributor acknowledgments +and/or dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section entitled @q{Endorsements}. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section as @q{Endorsements} +or to conflict in title with any Invariant Section. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled @q{Endorsements}, provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled @q{History} +in the various original documents, forming one section entitled +@q{History}; likewise combine any sections entitled @q{Acknowledgments}, +and any sections entitled @q{Dedications}. You must delete all sections +entitled @q{Endorsements.} + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an @q{aggregate}, and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License @q{or any later version} applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@subheading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being @var{list their titles}, with the + Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + A copy of the license is included in the section entitled @q{GNU + Free Documentation License}. +@end group +@end smallexample + +If you have no Invariant Sections, write @q{with no Invariant Sections} +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write @q{no Front-Cover Texts} instead of +@q{Front-Cover Texts being @var{list}}; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/Documentation/essay/henle-flat-bw.png b/Documentation/essay/henle-flat-bw.png new file mode 100644 index 0000000000..b47660f376 Binary files /dev/null and b/Documentation/essay/henle-flat-bw.png differ diff --git a/Documentation/essay/henle-flat-gray.png b/Documentation/essay/henle-flat-gray.png new file mode 100644 index 0000000000..20326b958a Binary files /dev/null and b/Documentation/essay/henle-flat-gray.png differ diff --git a/Documentation/essay/introduction.itely b/Documentation/essay/introduction.itely new file mode 100644 index 0000000000..6ba3f550e4 --- /dev/null +++ b/Documentation/essay/introduction.itely @@ -0,0 +1,816 @@ +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond-learning.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@c \version "2.12.0" + +@node Introduction +@chapter Introduction + +This chapter introduces readers to LilyPond and the +documentation. + +@menu +* Background:: +@end menu + + +@node Background +@section Background + +This section covers the overall goals and architecture of +LilyPond. + +@menu +* 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 +stamping the music into a zinc or pewter plate in mirror image. +The plate would be inked, the depressions caused by the cutting +and stamping would hold ink. An image was formed by pressing +paper to the plate. The stamping and cutting was completely done +by hand. Making a correction was cumbersome, if possible at all, +so the engraving had to be perfect in one go. Engraving was a +highly specialized skill; a craftsman had to complete around five +years of training before earning the title of master engraver, and +another five years of experience were necessary to become truly +skilled. + +Nowadays, all newly printed music is produced with computers. +This has obvious advantages; prints are cheaper to make, and +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. + + +@c introduce illustrating aspects of engraving, font... +The images below illustrate the difference between traditional +engraving and typical computer output, and the third picture shows +how LilyPond mimics the traditional look. The left picture shows +a scan of a flat symbol from an edition published in 2000. The +center depicts a symbol from a hand-engraved Bärenreiter edition +of the same music. The left scan illustrates typical flaws of +computer print: the staff lines are thin, the weight of the flat +symbol matches the light lines and it has a straight layout with +sharp corners. By contrast, the Bärenreiter flat has a bold, +almost voluptuous rounded look. Our flat symbol is designed +after, among others, this one. It is rounded, and its weight +harmonizes with the thickness of our staff lines, which are also +much thicker than lines in the computer edition. + +@multitable @columnfractions .125 .25 .25 .25 .125 +@item @tab +@ifnotinfo +@iftex +@image{henle-flat-gray,,4cm} +@end iftex +@ifnottex +@image{henle-flat-gray,,,png} +@end ifnottex + +@tab +@iftex +@image{baer-flat-gray,,4cm} +@end iftex +@ifnottex +@image{baer-flat-gray,,,png} +@end ifnottex + +@tab +@iftex +@image{lily-flat-bw,,4cm} +@end iftex +@ifnottex +@image{lily-flat-bw,,,png} +@end ifnottex +@end ifnotinfo +@ifinfo +@image{lilypond/henle-flat-bw,,,,png} @image{lilypond/baer-flat-bw,,,,png} +@image{lilypond/lily-flat-bw,,,,png} +@end ifinfo + +@item @tab +Henle (2000) +@tab +Bärenreiter (1950) +@tab +LilyPond Feta font (2003) + +@end multitable + + +@cindex musical symbols +@cindex font +@cindex blackness +@cindex balance + +@c introduce illustrating aspects of engraving, spacing... +In spacing, the distribution of space should reflect the durations +between notes. However, many modern scores adhere to the +durations with mathematical precision, which leads to poor +results. In the next example a motive is printed twice: once +using exact mathematical spacing, and once with corrections. Can +you spot which fragment is which? + +@cindex optical spacing +@c file spacing-optical. +@c need to include it here, because we want two images. +@lilypond +\paper { + ragged-right = ##t + indent = #0.0 +} + +music = { + c'4 e''4 e'4 b'4 | + \stemDown + b'8[ e'' a' e''] + \stemNeutral + e'8[ e'8 e'8 e'8] +} + +\score +{ + \music + \layout { + \context { + \Staff + \override NoteSpacing #'stem-spacing-correction = #0.6 + } + } +} +@end lilypond + +@lilypond +\paper { + ragged-right = ##t + indent = #0.0 +} + +music = { + c'4 e''4 e'4 b'4 | + \stemDown + b'8[ e'' a' e''] + \stemNeutral + e'8[ e'8 e'8 e'8] +} +\score +{ + \music + \layout { + \context { + \Staff + \override NoteSpacing #'stem-spacing-correction = #0.0 + \override NoteSpacing #'same-direction-correction = #0.0 + \override StaffSpacing #'stem-spacing-correction = #0.0 + } + } +} +@end lilypond + +@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, +the eye deceives us a little; not only does it notice the distance +between note heads, it also takes into account the distance +between consecutive stems. As a result, the notes of an +up-stem/@/down-stem combination should be put farther apart, and +the notes of a down-stem/@/up-stem combination should be put +closer together, all depending on the combined vertical positions +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. + + +Musicians are usually more absorbed with performing than with +studying the looks of a piece of music, so nitpicking about +typographical details may seem academical. But it is not. In +larger pieces with monotonous rhythms, spacing corrections lead to +subtle variations in the layout of every line, giving each one a +distinct visual signature. Without this signature all lines would +look the same, and they become like a labyrinth. If a musician +looks away once or has a lapse in concentration, the lines might +lose their place on the page. + +Similarly, the strong visual look of bold symbols on heavy staff +lines stands out better when the music is far away from the +reader, for example, if it is on a music stand. A careful +distribution of white space allows music to be set very tightly +without cluttering symbols together. The result minimizes the +number of page turns, which is a great advantage. + +This is a common characteristic of typography. Layout should be +pretty, not only for its own sake, but especially because it helps +the reader in her task. For performance material like sheet +music, this is of double importance: musicians have a limited +amount of attention. The less attention they need for reading, +the more they can focus on playing the music. In other words, +better typography translates to better performances. + +These examples demonstrate that music typography is an art that is +subtle and complex, and that producing it requires considerable +expertise, which musicians usually do not have. LilyPond is our +effort to bring the graphical excellence of hand-engraved music to +the computer age, and make it available to normal musicians. We +have tuned our algorithms, font-designs, and program settings to +produce prints that match the quality of the old editions we love +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? + +The answer is: we cannot. Typography relies on human judgment of +appearance, so people cannot be replaced completely. However, +much of the dull work can be automated. If LilyPond solves most +of the common situations correctly, this will be a huge +improvement over existing software. The remaining cases can be +tuned by hand. Over the course of years, the software can be +refined to do more and more things automatically, so manual +overrides are less and less necessary. + +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: + +@itemize + +@item When LilyPond makes mistakes, users need to override +formatting decisions. Therefore, the user must have access to the +formatting engine. Hence, rules and settings cannot be fixed by +us at compile-time but must be accessible for users at run-time. + +@item Engraving is a matter of visual judgment, and therefore a +matter of taste. As knowledgeable as we are, users can disagree +with our personal decisions. Therefore, the definitions of +typographical style must also be accessible to the user. + +@item Finally, we continually refine the formatting algorithms, so +we need a flexible approach to rules. The C++ language forces a +certain method of grouping rules that do not match well with how +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 +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. + +Scheme variables control layout decisions. For example, many +graphical objects have a direction variable that encodes the +choice between up and down (or left and right). Here you see two +chords, with accents and arpeggios. In the first chord, the +graphical objects have all directions down (or left). The second +chord has all directions up (right). + +@lilypond[quote,ragged-right] +\new Score \with { + \override SpacingSpanner #'spacing-increment = #3 + \override TimeSignature #'transparent = ##t +} \relative c' { + \stemDown 4_>-\arpeggio + \override Arpeggio #'direction = #RIGHT + \stemUp 4^>-\arpeggio +} +@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 +value. For example, the thickness of many lines -- a +characteristic of typographical style -- is a variable with a +preset value. You are free to alter this value, giving your score +a different typographical impression. + +@lilypond[quote,ragged-right] +fragment = { + \clef bass f8 as8 + c'4-~ c'16 as g f e16 g bes c' des'4 +} +<< + \new Staff \fragment + \new Staff \with { + \override Beam #'thickness = #0.3 + \override Stem #'thickness = #0.5 + \override Bar #'thickness = #3.6 + \override Tie #'thickness = #2.2 + \override StaffSymbol #'thickness = #3.0 + \override Tie #'extra-offset = #'(0 . 0.3) + } + \fragment +>> +@end lilypond + +Formatting rules are also preset variables: each object has +variables containing procedures. These procedures perform the +actual formatting, and by substituting different ones, we can +change the appearance of objects. In the following example, the +rule which note head objects are used to produce their symbol is +changed during the music fragment. + +@lilypond[quote,ragged-right] +#(set-global-staff-size 30) + +#(define (mc-squared grob orig current) + (let* ((interfaces (ly:grob-interfaces grob)) + (pos (ly:grob-property grob 'staff-position))) + (if (memq 'note-head-interface interfaces) + (begin + (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 + 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 + + +@node What symbols to engrave? +@unnumberedsubsec What symbols to engrave? + +@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 +should be printed, in other words what notation to use. + +Common music notation is a system of recording music that has +evolved over the past 1000 years. The form that is now in common +use dates from the early renaissance. Although the basic form +(i.e., note heads on a 5-line staff) has not changed, the details +still evolve to express the innovations of contemporary notation. +Hence, it encompasses some 500 years of music. Its applications +range from monophonic melodies to monstrous counterpoints for +large orchestras. + +How can we get a grip on such a many-headed beast, and force it +into the confines of a computer program? Our solution is to break +up the problem of notation (as opposed to engraving, i.e., +typography) into digestible and programmable chunks: every type of +symbol is handled by a separate module, a so-called plug-in. Each +plug-in is completely modular and independent, so each can be +developed and improved separately. Such plug-ins are called +@code{engraver}s, by analogy with craftsmen who translate musical +ideas to graphic symbols. + +In the following example, we see how we start out with a plug-in +for note heads, the @code{Note_heads_engraver}. + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" + +\score { + \topVoice + \layout { + \context { + \Voice + \remove "Stem_engraver" + \remove "Phrasing_slur_engraver" + \remove "Slur_engraver" + \remove "Script_engraver" + \remove "Beam_engraver" + \remove "Auto_beam_engraver" + } + \context { + \Staff + \remove "Accidental_engraver" + \remove "Key_engraver" + \remove "Clef_engraver" + \remove "Bar_engraver" + \remove "Time_signature_engraver" + \remove "Staff_symbol_engraver" + \consists "Pitch_squash_engraver" + } + } +} +@end lilypond + +@noindent +Then a @code{Staff_symbol_engraver} adds the staff + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" + +\score { + \topVoice + \layout { + \context { + \Voice + \remove "Stem_engraver" + \remove "Phrasing_slur_engraver" + \remove "Slur_engraver" + \remove "Script_engraver" + \remove "Beam_engraver" + \remove "Auto_beam_engraver" + } + \context { + \Staff + \remove "Accidental_engraver" + \remove "Key_engraver" + \remove "Clef_engraver" + \remove "Bar_engraver" + \consists "Pitch_squash_engraver" + \remove "Time_signature_engraver" + } + } +} +@end lilypond + +@noindent +the @code{Clef_engraver} defines a reference point for the staff + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" + +\score { + \topVoice + \layout { + \context { + \Voice + \remove "Stem_engraver" + \remove "Phrasing_slur_engraver" + \remove "Slur_engraver" + \remove "Script_engraver" + \remove "Beam_engraver" + \remove "Auto_beam_engraver" + } + \context { + \Staff + \remove "Accidental_engraver" + \remove "Key_engraver" + \remove "Bar_engraver" + \remove "Time_signature_engraver" + } + } +} +@end lilypond + +@noindent +and the @code{Stem_engraver} adds stems. + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" + +\score { + \topVoice + \layout { + \context { + \Voice + \remove "Phrasing_slur_engraver" + \remove "Slur_engraver" + \remove "Script_engraver" + \remove "Beam_engraver" + \remove "Auto_beam_engraver" + } + \context { + \Staff + \remove "Accidental_engraver" + \remove "Key_engraver" + \remove "Bar_engraver" + \remove "Time_signature_engraver" + } + } +} +@end lilypond + +@noindent +The @code{Stem_engraver} is notified of any note head coming +along. Every time one (or more, for a chord) note head is seen, a +stem object is created and connected to the note head. By adding +engravers for beams, slurs, accents, accidentals, bar lines, time +signature, and key signature, we get a complete piece of notation. + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" +\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. + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" +\new Staff << \topVoice \\ \botVoice >> +@end lilypond + +In this situation, the accidentals and staff are shared, but the +stems, slurs, beams, etc., are private to each voice. Hence, +engravers should be grouped. The engravers for note heads, stems, +slurs, etc., go into a group called @q{Voice context,} while the +engravers for key, accidental, bar, etc., go into a group called +@q{Staff context.} In the case of polyphony, a single Staff +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 +Internals Reference: @rinternals{Contexts}. + + +@lilypond[quote,ragged-right] +\include "engraver-example.ily" +\score { + << + \new Staff << \topVoice \\ \botVoice >> + \new Staff << \pah \\ \hoom >> + >> +} +@end lilypond + + +@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 +define what music really is? Instead of trying to find an answer, +we have reversed the question. We write a program capable of +producing sheet music, and adjust the format to be as lean as +possible. When the format can no longer be trimmed down, by +definition we are left with content itself. Our program serves as +a formal definition of a music document. + +The syntax is also the user-interface for LilyPond, hence it is +easy to type: + +@example +@{ + c'4 d'8 +@} +@end example + +@noindent +to create a quarter note C1 (middle C) and an eighth note D1 (D +above middle C). + +@lilypond[quote] +{ + c'4 d'8 +} +@end lilypond + +On a microscopic scale, such syntax is easy to use. On a larger +scale, syntax also needs structure. How else can you enter +complex pieces like symphonies and operas? The structure is +formed by the concept of music expressions: by combining small +fragments of music into larger ones, more complex music can be +expressed. For example + +@lilypond[quote,verbatim,fragment,relative=1] +f4 +@end lilypond + +@noindent +Simultaneous notes can be constructed by enclosing them with +@code{<<} and @code{>>}: + +@example +<> +@end example + +@lilypond[quote,fragment,relative=1] +\new Voice { <> } +@end lilypond + +@noindent +This expression is put in sequence by enclosing it in curly braces +@code{@{@tie{}@dots{}@tie{}@}}: + +@example +@{ f4 <> @} +@end example + +@lilypond[quote,relative=1,fragment] +{ f4 <> } +@end lilypond + +@noindent +The above is also an expression, and so it may be combined again +with another simultaneous expression (a half note) using +@code{<<}, @code{\\}, and @code{>>}: + +@example +<< g2 \\ @{ f4 <> @} >> +@end example + +@lilypond[quote,fragment,relative=2] +\new Voice { << g2 \\ { f4 <> } >> } +@end lilypond + +Such recursive structures can be specified neatly and formally in +a context-free grammar. The parsing code is also generated from +this grammar. In other words, the syntax of LilyPond is clearly +and unambiguously defined. + +User-interfaces and syntax are what people see and deal with most. +They are partly a matter of taste, and also subject of much +discussion. Although discussions on taste do have their merit, +they are not very productive. In the larger picture of LilyPond, +the importance of input syntax is small: inventing neat syntax is +easy, while writing decent formatting code is much harder. This +is also illustrated by the line-counts for the respective +components: parsing and representation take up less than 10% of +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 +tasks. The simplest application is printing notes. + +@lilypond[quote,relative=1] +{ + \time 2/4 + c4 c g'4 g a4 a g2 +} +@end lilypond + +@noindent +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' g a a g2 + } + \addlyrics { twin -- kle twin -- kle lit -- tle star } +>> +@end lilypond + +Polyphonic notation and piano music can also be printed. The +following example combines some more exotic constructs. + +@lilypond[quote] +\header { + title = "Screech and boink" + subtitle = "Random complex notation" + composer = "Han-Wen Nienhuys" +} + +\score { + \context PianoStaff << + \new Staff = "up" { + \time 4/8 + \key c \minor + << { + \revert Stem #'direction + \change Staff = down + \set subdivideBeams = ##t + g16.[ + \change Staff = up + c'''32 + \change Staff = down + g32 + \change Staff = up + c'''32 + \change Staff = down + g16] + \change Staff = up + \stemUp + \set followVoice = ##t + c'''32([ b''16 a''16 gis''16 g''32)] + } \\ { + s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d''] + } \\ { + s4 \autoBeamOff d''8.. f''32 + } \\ { + s4 es''4 + } >> + } + + \new Staff = "down" { + \clef bass + \key c \minor + \set subdivideBeams = ##f + \override Stem #'french-beaming = ##t + \override Beam #'thickness = #0.3 + \override Stem #'thickness = #4.0 + g'16[ b16 fis16 g16] + << \makeClusters { + as16 + + + } \\ { + \override Staff.Arpeggio #'arpeggio-direction =#down + 4\arpeggio + } + >> } + >> + \midi { + \context { + \Score + tempoWholesPerMinute = #(ly:make-moment 60 8) + } + } + \layout { + \context { + \Staff + \consists Horizontal_bracket_engraver + } + } +} +@end lilypond + +The fragments shown above have all been written by hand, but that +is not a requirement. Since the formatting engine is mostly +automatic, it can serve as an output means for other programs that +manipulate music. For example, it can also be used to convert +databases of musical fragments to images for use on websites and +multimedia presentations. + +This manual also shows an application: the input format is text, +and can therefore be easily embedded in other text-based formats +such as @LaTeX{}, HTML, or in the case of this manual, Texinfo. +By means of a special program, the input fragments can be replaced +by music images in the resulting PDF or HTML output files. This +makes it easy to mix music and text in documents. + + + diff --git a/Documentation/essay/lily-flat-bw.png b/Documentation/essay/lily-flat-bw.png new file mode 100644 index 0000000000..09ce34e7c5 Binary files /dev/null and b/Documentation/essay/lily-flat-bw.png differ diff --git a/Documentation/essay/lilypond-essay.tely b/Documentation/essay/lilypond-essay.tely new file mode 100644 index 0000000000..0e44ce80e8 --- /dev/null +++ b/Documentation/essay/lilypond-essay.tely @@ -0,0 +1,135 @@ +\input texinfo @c -*- coding: utf-8; mode: texinfo; -*- +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore +@setfilename lilypond-learning.info +@settitle GNU LilyPond essay +@documentencoding UTF-8 +@documentlanguage en + +@include macros.itexi + +@afourpaper + + +@c don't remove this comment. +@ignore +@omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival +@omfdescription essay of the LilyPond music engraving system +@omftype program usage +@omfcategory Applications|Publishing +@omflanguage English +@end ignore + +@ifnottex +@node Top +@top GNU LilyPond --- essay +@end ifnottex + + +@ifhtml +@ifclear bigpage +This document is also available as a +@uref{source/Documentation/user/lilypond-learning.pdf,PDF} and as +@uref{source/Documentation/user/lilypond-learning-big-page.html,one big page}. +@end ifclear +@ifset bigpage +This document is also available as a +@uref{source/Documentation/user/lilypond-learning.pdf,PDF} and as +@uref{source/Documentation/user/lilypond-learning/index.html,HTML indexed multiple pages}. +@end ifset +@end ifhtml + + +@c This produces the unified index +@syncodeindex fn cp +@syncodeindex vr cp + + +@finalout + +@titlepage +@title LilyPond +@subtitle The music typesetter +@titlefont{essay} +@author The LilyPond development team + + +Copyright @copyright{} 1999--2009 by the authors + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with no Invariant Sections. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end quotation + +@vskip 20pt + +For LilyPond version @version{} +@end titlepage + +@copying +Copyright @copyright{} 1999--2009 by the authors + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with no Invariant Sections. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end quotation +@end copying + +@ifnottex +This file documents GNU LilyPond for beginners. + +Copyright 1999--2009 by the authors + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with no Invariant Sections. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end quotation +@end ifnottex + +@ifnottex +This is the essay (LM) for GNU LilyPond version @version{}. +For more information about how this fits with the other +@c documentation, see @ref{About the documentation}. + +@cindex web site +@cindex URL + +More information can be found at +@uref{http://@/www@/.lilypond@/.org/}. The website contains on-line copies +of this and other documentation. + +@menu +* Introduction:: What, Why, How. +* GNU Free Documentation License:: License of this document. +@end menu +@end ifnottex + +@contents + + +@include introduction.itely + +@include fdl.itexi + +@c @n ode LilyPond index +@c @a ppendix LilyPond index + +@c @printindex cp + +@bye diff --git a/Documentation/essay/macros.itexi b/Documentation/essay/macros.itexi new file mode 100644 index 0000000000..9dbf8a8ff3 --- /dev/null +++ b/Documentation/essay/macros.itexi @@ -0,0 +1,402 @@ +@c -*- coding: us-ascii; mode: texinfo; -*- +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + + +@include version.itexi + + +@c Don't replace quotes with directed quotes. + +@set txicodequoteundirected +@set txicodequotebacktick + + + +@c ***** Displaying text ***** + +@c We need this since @q{\} doesn't work with makeinfo 4.11 -- +@c say @q{@bs{}} instead. + +@macro bs +\\ +@end macro + + +@c To get decent quotes in `foo' and ``foo''. + +@macro q{TEXT} +@quoteleft{}\TEXT\@quoteright{} +@end macro + +@macro qq{TEXT} +@quotedblleft{}\TEXT\@quotedblright{} +@end macro + + +@ifhtml + +@macro warning{TEXT} +@cartouche +@b{Note:} \TEXT\ +@end cartouche +@end macro + +@end ifhtml + +@ifnothtml + +@macro warning{TEXT} +@quotation +@quotation +@cartouche +@b{Note:} \TEXT\ +@end cartouche +@end quotation +@end quotation +@end macro + +@end ifnothtml + + +@ifnotinfo + +@macro notation{TEXT} +@var{\TEXT\} +@end macro + +@end ifnotinfo + +@ifinfo + +@macro notation{TEXT} +\TEXT\ +@end macro + +@end ifinfo + + +@macro smallspace +@sp 1 +@end macro + + + +@c ***** Displaying images not generated by lilypond-book ***** + +@c Current installation setup of Info docs requires that all images are +@c expected to be found in the `lilypond/' subdirectory. `lilypond-book' +@c already generates proper @image commands for images of music; these +@c macro definitions do the same for other images. + +@ifnotinfo + +@macro sourceimage{FILENAME,WIDTH,HEIGHT,ALTTEXT} +@image{\FILENAME\,\WIDTH\,\HEIGHT\,\ALTTEXT\} +@end macro + +@end ifnotinfo + +@ifinfo + +@macro sourceimage{FILENAME,WIDTH,HEIGHT,ALTTEXT} +@image{lilypond/\FILENAME\,\WIDTH\,\HEIGHT\,\ALTTEXT\} +@end macro + +@end ifinfo + + + +@c ***** Headings in a doc subsection ***** + +@c Don't insert an empty line after @predefined! Right now +@c it doesn't matter, but a future implementation will probably +@c add some code which needs this restriction. + +@macro predefined +@noindent +@subsubheading Predefined commands +@end macro + +@c The next macro is a dummy currently since texinfo doesn't +@c provide a real ragged-right environment yet. +@c +@c Due to a bug in texi2html (texi2html.pl CVS versions <= 1.245) +@c the macro must not be empty. + +@macro endpredefined +@c +@end macro + + +@macro snippets +@noindent +@subsubheading Selected Snippets +@end macro + + +@c Don't insert an empty line after @seealso! Otherwise we get +@c unwanted extra vertical space in the PDF output. + +@macro seealso +@noindent +@subsubheading See also +@indent +@end macro + + +@macro knownissues +@noindent +@subsubheading Known issues and warnings +@end macro + + +@macro lydoctitle {TEXT} +@emph{\TEXT\} +@end macro + + +@c Don't remove the `@c' within the macro definition! See section 19.3, +@c `Macro Details and Caveats', in the texinfo info file for explanation. + +@macro funindex {TEXT} +@findex \TEXT\ +@kindex \TEXT\ +@c +@end macro + + + +@c ***** Links and references ***** + +@c Definitions for references: +@c +@c @rglos +@c @rlearning +@c @ruser +@c @rprogram +@c @rlsr +@c @rinternals +@c +@c All these also have a @...named version which allows to specify the +@c displayed text for the reference as second argument. +@c +@c ***** HTML + bigpage is a special case (other manual names); all other +@c formats are treated similarly. + + +@c *** not TeX *** + +@ifnottex + +@c ** bigpage ** + +@ifset bigpage + +@macro rglos{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,music-glossary-big-page,Music Glossary} +@end macro + +@macro rglosnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,music-glossary-big-page,Music Glossary} +@end macro + +@macro rlearning{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-learning-big-page,Learning Manual} +@end macro + +@macro rlearningnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-learning-big-page,Learning Manual} +@end macro + +@macro ruser{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-big-page,Notation Reference} +@end macro + +@macro rusernamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-big-page,Notation Reference} +@end macro + +@macro rprogram{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-program-big-page,Application Usage} +@end macro + +@macro rprogramnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-program-big-page,Application Usage} +@end macro + +@macro rlsr{TEXT} +@ref{\TEXT\,,,lilypond-snippets-big-page,Snippets} +@end macro + +@macro rlsrnamed{TEXT,DISPLAY} +@ref{\TEXT\,,\DISPLAY\,lilypond-snippets-big-page,Snippets} +@end macro + +@macro rinternals{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-internals-big-page,Internals Reference} +@end macro + +@macro rinternalsnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-internals-big-page,Internals Reference} +@end macro + +@end ifset + + +@c ** not bigpage ** + +@ifclear bigpage + +@macro rglos{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,music-glossary,Music Glossary} +@end macro + +@macro rglosnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary} +@end macro + +@macro rlearning{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-learning,Learning Manual} +@end macro + +@macro rlearningnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-learning,Learning Manual} +@end macro + +@macro ruser{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond,Notation Reference} +@end macro + +@macro rusernamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference} +@end macro + +@macro rprogram{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-program,Application Usage} +@end macro + +@macro rprogramnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage} +@end macro + +@macro rlsr{TEXT} +@ref{\TEXT\,,,lilypond-snippets,Snippets} +@end macro + +@macro rlsrnamed{TEXT,DISPLAY} +@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets} +@end macro + +@macro rinternals{TEXT} +@vindex \TEXT\ +@ref{\TEXT\,,,lilypond-internals,Internals Reference} +@end macro + +@macro rinternalsnamed{TEXT,DISPLAY} +@vindex \TEXT\ +@ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference} +@end macro + +@end ifclear + +@end ifnottex + + +@c *** TeX *** + +@iftex + +@c All commands below should work in the middle of the line; +@c we thus must not use @vindex directly since it works only if placed +@c on a line of its own. To overcome this problem, we define a +@c replacement macro using the internal definition of @vindex which +@c delimits arguments in the standard way (i.e., with braces). + +@tex +\gdef\lilyvindex#1{\doind{vr}{\code #1}\ignorespaces} +@end tex + +@macro rglos{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,music-glossary,Music Glossary} +@end macro + +@macro rglosnamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary} +@end macro + +@macro rlearning{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,lilypond-learning,Learning Manual} +@end macro + +@macro rlearningnamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,lilypond-learning,Learning Manual} +@end macro + +@macro ruser{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,lilypond,Notation Reference} +@end macro + +@macro rusernamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,lilypond,Notation Reference} +@end macro + +@macro rprogram{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,lilypond-program,Application Usage} +@end macro + +@macro rprogramnamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,lilypond-program,Application Usage} +@end macro + +@macro rlsr{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,lilypond-snippets,Snippets} +@end macro + +@macro rlsrnamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets} +@end macro + +@macro rinternals{TEXT} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,,lilypond-internals,Internals Reference} +@end macro + +@macro rinternalsnamed{TEXT,DISPLAY} +@lilyvindex{\TEXT\} +@ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference} +@end macro + +@end iftex diff --git a/Documentation/user/baer-flat-bw.png b/Documentation/user/baer-flat-bw.png deleted file mode 100644 index bb25bd1903..0000000000 Binary files a/Documentation/user/baer-flat-bw.png and /dev/null differ diff --git a/Documentation/user/baer-flat-gray.png b/Documentation/user/baer-flat-gray.png deleted file mode 100644 index 08cd338380..0000000000 Binary files a/Documentation/user/baer-flat-gray.png and /dev/null differ diff --git a/Documentation/user/henle-flat-bw.png b/Documentation/user/henle-flat-bw.png deleted file mode 100644 index b47660f376..0000000000 Binary files a/Documentation/user/henle-flat-bw.png and /dev/null differ diff --git a/Documentation/user/henle-flat-gray.png b/Documentation/user/henle-flat-gray.png deleted file mode 100644 index 20326b958a..0000000000 Binary files a/Documentation/user/henle-flat-gray.png and /dev/null differ diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index b031f13ab3..ab40eec69f 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -16,804 +16,10 @@ This chapter introduces readers to LilyPond and the documentation. @menu -* Background:: * About the documentation:: @end menu -@node Background -@section Background - -This section covers the overall goals and architecture of -LilyPond. - -@menu -* 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 -stamping the music into a zinc or pewter plate in mirror image. -The plate would be inked, the depressions caused by the cutting -and stamping would hold ink. An image was formed by pressing -paper to the plate. The stamping and cutting was completely done -by hand. Making a correction was cumbersome, if possible at all, -so the engraving had to be perfect in one go. Engraving was a -highly specialized skill; a craftsman had to complete around five -years of training before earning the title of master engraver, and -another five years of experience were necessary to become truly -skilled. - -Nowadays, all newly printed music is produced with computers. -This has obvious advantages; prints are cheaper to make, and -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. - - -@c introduce illustrating aspects of engraving, font... -The images below illustrate the difference between traditional -engraving and typical computer output, and the third picture shows -how LilyPond mimics the traditional look. The left picture shows -a scan of a flat symbol from an edition published in 2000. The -center depicts a symbol from a hand-engraved Bärenreiter edition -of the same music. The left scan illustrates typical flaws of -computer print: the staff lines are thin, the weight of the flat -symbol matches the light lines and it has a straight layout with -sharp corners. By contrast, the Bärenreiter flat has a bold, -almost voluptuous rounded look. Our flat symbol is designed -after, among others, this one. It is rounded, and its weight -harmonizes with the thickness of our staff lines, which are also -much thicker than lines in the computer edition. - -@multitable @columnfractions .125 .25 .25 .25 .125 -@item @tab -@ifnotinfo -@iftex -@image{henle-flat-gray,,4cm} -@end iftex -@ifnottex -@image{henle-flat-gray,,,png} -@end ifnottex - -@tab -@iftex -@image{baer-flat-gray,,4cm} -@end iftex -@ifnottex -@image{baer-flat-gray,,,png} -@end ifnottex - -@tab -@iftex -@image{lily-flat-bw,,4cm} -@end iftex -@ifnottex -@image{lily-flat-bw,,,png} -@end ifnottex -@end ifnotinfo -@ifinfo -@image{lilypond/henle-flat-bw,,,,png} @image{lilypond/baer-flat-bw,,,,png} -@image{lilypond/lily-flat-bw,,,,png} -@end ifinfo - -@item @tab -Henle (2000) -@tab -Bärenreiter (1950) -@tab -LilyPond Feta font (2003) - -@end multitable - - -@cindex musical symbols -@cindex font -@cindex blackness -@cindex balance - -@c introduce illustrating aspects of engraving, spacing... -In spacing, the distribution of space should reflect the durations -between notes. However, many modern scores adhere to the -durations with mathematical precision, which leads to poor -results. In the next example a motive is printed twice: once -using exact mathematical spacing, and once with corrections. Can -you spot which fragment is which? - -@cindex optical spacing -@c file spacing-optical. -@c need to include it here, because we want two images. -@lilypond -\paper { - ragged-right = ##t - indent = #0.0 -} - -music = { - c'4 e''4 e'4 b'4 | - \stemDown - b'8[ e'' a' e''] - \stemNeutral - e'8[ e'8 e'8 e'8] -} - -\score -{ - \music - \layout { - \context { - \Staff - \override NoteSpacing #'stem-spacing-correction = #0.6 - } - } -} -@end lilypond - -@lilypond -\paper { - ragged-right = ##t - indent = #0.0 -} - -music = { - c'4 e''4 e'4 b'4 | - \stemDown - b'8[ e'' a' e''] - \stemNeutral - e'8[ e'8 e'8 e'8] -} -\score -{ - \music - \layout { - \context { - \Staff - \override NoteSpacing #'stem-spacing-correction = #0.0 - \override NoteSpacing #'same-direction-correction = #0.0 - \override StaffSpacing #'stem-spacing-correction = #0.0 - } - } -} -@end lilypond - -@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, -the eye deceives us a little; not only does it notice the distance -between note heads, it also takes into account the distance -between consecutive stems. As a result, the notes of an -up-stem/@/down-stem combination should be put farther apart, and -the notes of a down-stem/@/up-stem combination should be put -closer together, all depending on the combined vertical positions -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. - - -Musicians are usually more absorbed with performing than with -studying the looks of a piece of music, so nitpicking about -typographical details may seem academical. But it is not. In -larger pieces with monotonous rhythms, spacing corrections lead to -subtle variations in the layout of every line, giving each one a -distinct visual signature. Without this signature all lines would -look the same, and they become like a labyrinth. If a musician -looks away once or has a lapse in concentration, the lines might -lose their place on the page. - -Similarly, the strong visual look of bold symbols on heavy staff -lines stands out better when the music is far away from the -reader, for example, if it is on a music stand. A careful -distribution of white space allows music to be set very tightly -without cluttering symbols together. The result minimizes the -number of page turns, which is a great advantage. - -This is a common characteristic of typography. Layout should be -pretty, not only for its own sake, but especially because it helps -the reader in her task. For performance material like sheet -music, this is of double importance: musicians have a limited -amount of attention. The less attention they need for reading, -the more they can focus on playing the music. In other words, -better typography translates to better performances. - -These examples demonstrate that music typography is an art that is -subtle and complex, and that producing it requires considerable -expertise, which musicians usually do not have. LilyPond is our -effort to bring the graphical excellence of hand-engraved music to -the computer age, and make it available to normal musicians. We -have tuned our algorithms, font-designs, and program settings to -produce prints that match the quality of the old editions we love -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? - -The answer is: we cannot. Typography relies on human judgment of -appearance, so people cannot be replaced completely. However, -much of the dull work can be automated. If LilyPond solves most -of the common situations correctly, this will be a huge -improvement over existing software. The remaining cases can be -tuned by hand. Over the course of years, the software can be -refined to do more and more things automatically, so manual -overrides are less and less necessary. - -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: - -@itemize - -@item When LilyPond makes mistakes, users need to override -formatting decisions. Therefore, the user must have access to the -formatting engine. Hence, rules and settings cannot be fixed by -us at compile-time but must be accessible for users at run-time. - -@item Engraving is a matter of visual judgment, and therefore a -matter of taste. As knowledgeable as we are, users can disagree -with our personal decisions. Therefore, the definitions of -typographical style must also be accessible to the user. - -@item Finally, we continually refine the formatting algorithms, so -we need a flexible approach to rules. The C++ language forces a -certain method of grouping rules that do not match well with how -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 -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. - -Scheme variables control layout decisions. For example, many -graphical objects have a direction variable that encodes the -choice between up and down (or left and right). Here you see two -chords, with accents and arpeggios. In the first chord, the -graphical objects have all directions down (or left). The second -chord has all directions up (right). - -@lilypond[quote,ragged-right] -\new Score \with { - \override SpacingSpanner #'spacing-increment = #3 - \override TimeSignature #'transparent = ##t -} \relative c' { - \stemDown 4_>-\arpeggio - \override Arpeggio #'direction = #RIGHT - \stemUp 4^>-\arpeggio -} -@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 -value. For example, the thickness of many lines -- a -characteristic of typographical style -- is a variable with a -preset value. You are free to alter this value, giving your score -a different typographical impression. - -@lilypond[quote,ragged-right] -fragment = { - \clef bass f8 as8 - c'4-~ c'16 as g f e16 g bes c' des'4 -} -<< - \new Staff \fragment - \new Staff \with { - \override Beam #'thickness = #0.3 - \override Stem #'thickness = #0.5 - \override Bar #'thickness = #3.6 - \override Tie #'thickness = #2.2 - \override StaffSymbol #'thickness = #3.0 - \override Tie #'extra-offset = #'(0 . 0.3) - } - \fragment ->> -@end lilypond - -Formatting rules are also preset variables: each object has -variables containing procedures. These procedures perform the -actual formatting, and by substituting different ones, we can -change the appearance of objects. In the following example, the -rule which note head objects are used to produce their symbol is -changed during the music fragment. - -@lilypond[quote,ragged-right] -#(set-global-staff-size 30) - -#(define (mc-squared grob orig current) - (let* ((interfaces (ly:grob-interfaces grob)) - (pos (ly:grob-property grob 'staff-position))) - (if (memq 'note-head-interface interfaces) - (begin - (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 - 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 - - -@node What symbols to engrave? -@unnumberedsubsec What symbols to engrave? - -@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 -should be printed, in other words what notation to use. - -Common music notation is a system of recording music that has -evolved over the past 1000 years. The form that is now in common -use dates from the early renaissance. Although the basic form -(i.e., note heads on a 5-line staff) has not changed, the details -still evolve to express the innovations of contemporary notation. -Hence, it encompasses some 500 years of music. Its applications -range from monophonic melodies to monstrous counterpoints for -large orchestras. - -How can we get a grip on such a many-headed beast, and force it -into the confines of a computer program? Our solution is to break -up the problem of notation (as opposed to engraving, i.e., -typography) into digestible and programmable chunks: every type of -symbol is handled by a separate module, a so-called plug-in. Each -plug-in is completely modular and independent, so each can be -developed and improved separately. Such plug-ins are called -@code{engraver}s, by analogy with craftsmen who translate musical -ideas to graphic symbols. - -In the following example, we see how we start out with a plug-in -for note heads, the @code{Note_heads_engraver}. - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" - -\score { - \topVoice - \layout { - \context { - \Voice - \remove "Stem_engraver" - \remove "Phrasing_slur_engraver" - \remove "Slur_engraver" - \remove "Script_engraver" - \remove "Beam_engraver" - \remove "Auto_beam_engraver" - } - \context { - \Staff - \remove "Accidental_engraver" - \remove "Key_engraver" - \remove "Clef_engraver" - \remove "Bar_engraver" - \remove "Time_signature_engraver" - \remove "Staff_symbol_engraver" - \consists "Pitch_squash_engraver" - } - } -} -@end lilypond - -@noindent -Then a @code{Staff_symbol_engraver} adds the staff - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" - -\score { - \topVoice - \layout { - \context { - \Voice - \remove "Stem_engraver" - \remove "Phrasing_slur_engraver" - \remove "Slur_engraver" - \remove "Script_engraver" - \remove "Beam_engraver" - \remove "Auto_beam_engraver" - } - \context { - \Staff - \remove "Accidental_engraver" - \remove "Key_engraver" - \remove "Clef_engraver" - \remove "Bar_engraver" - \consists "Pitch_squash_engraver" - \remove "Time_signature_engraver" - } - } -} -@end lilypond - -@noindent -the @code{Clef_engraver} defines a reference point for the staff - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" - -\score { - \topVoice - \layout { - \context { - \Voice - \remove "Stem_engraver" - \remove "Phrasing_slur_engraver" - \remove "Slur_engraver" - \remove "Script_engraver" - \remove "Beam_engraver" - \remove "Auto_beam_engraver" - } - \context { - \Staff - \remove "Accidental_engraver" - \remove "Key_engraver" - \remove "Bar_engraver" - \remove "Time_signature_engraver" - } - } -} -@end lilypond - -@noindent -and the @code{Stem_engraver} adds stems. - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" - -\score { - \topVoice - \layout { - \context { - \Voice - \remove "Phrasing_slur_engraver" - \remove "Slur_engraver" - \remove "Script_engraver" - \remove "Beam_engraver" - \remove "Auto_beam_engraver" - } - \context { - \Staff - \remove "Accidental_engraver" - \remove "Key_engraver" - \remove "Bar_engraver" - \remove "Time_signature_engraver" - } - } -} -@end lilypond - -@noindent -The @code{Stem_engraver} is notified of any note head coming -along. Every time one (or more, for a chord) note head is seen, a -stem object is created and connected to the note head. By adding -engravers for beams, slurs, accents, accidentals, bar lines, time -signature, and key signature, we get a complete piece of notation. - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" -\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. - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" -\new Staff << \topVoice \\ \botVoice >> -@end lilypond - -In this situation, the accidentals and staff are shared, but the -stems, slurs, beams, etc., are private to each voice. Hence, -engravers should be grouped. The engravers for note heads, stems, -slurs, etc., go into a group called @q{Voice context,} while the -engravers for key, accidental, bar, etc., go into a group called -@q{Staff context.} In the case of polyphony, a single Staff -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 -Internals Reference: @rinternals{Contexts}. - - -@lilypond[quote,ragged-right] -\include "engraver-example.ily" -\score { - << - \new Staff << \topVoice \\ \botVoice >> - \new Staff << \pah \\ \hoom >> - >> -} -@end lilypond - - -@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 -define what music really is? Instead of trying to find an answer, -we have reversed the question. We write a program capable of -producing sheet music, and adjust the format to be as lean as -possible. When the format can no longer be trimmed down, by -definition we are left with content itself. Our program serves as -a formal definition of a music document. - -The syntax is also the user-interface for LilyPond, hence it is -easy to type: - -@example -@{ - c'4 d'8 -@} -@end example - -@noindent -to create a quarter note C1 (middle C) and an eighth note D1 (D -above middle C). - -@lilypond[quote] -{ - c'4 d'8 -} -@end lilypond - -On a microscopic scale, such syntax is easy to use. On a larger -scale, syntax also needs structure. How else can you enter -complex pieces like symphonies and operas? The structure is -formed by the concept of music expressions: by combining small -fragments of music into larger ones, more complex music can be -expressed. For example - -@lilypond[quote,verbatim,fragment,relative=1] -f4 -@end lilypond - -@noindent -Simultaneous notes can be constructed by enclosing them with -@code{<<} and @code{>>}: - -@example -<> -@end example - -@lilypond[quote,fragment,relative=1] -\new Voice { <> } -@end lilypond - -@noindent -This expression is put in sequence by enclosing it in curly braces -@code{@{@tie{}@dots{}@tie{}@}}: - -@example -@{ f4 <> @} -@end example - -@lilypond[quote,relative=1,fragment] -{ f4 <> } -@end lilypond - -@noindent -The above is also an expression, and so it may be combined again -with another simultaneous expression (a half note) using -@code{<<}, @code{\\}, and @code{>>}: - -@example -<< g2 \\ @{ f4 <> @} >> -@end example - -@lilypond[quote,fragment,relative=2] -\new Voice { << g2 \\ { f4 <> } >> } -@end lilypond - -Such recursive structures can be specified neatly and formally in -a context-free grammar. The parsing code is also generated from -this grammar. In other words, the syntax of LilyPond is clearly -and unambiguously defined. - -User-interfaces and syntax are what people see and deal with most. -They are partly a matter of taste, and also subject of much -discussion. Although discussions on taste do have their merit, -they are not very productive. In the larger picture of LilyPond, -the importance of input syntax is small: inventing neat syntax is -easy, while writing decent formatting code is much harder. This -is also illustrated by the line-counts for the respective -components: parsing and representation take up less than 10% of -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 -tasks. The simplest application is printing notes. - -@lilypond[quote,relative=1] -{ - \time 2/4 - c4 c g'4 g a4 a g2 -} -@end lilypond - -@noindent -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' g a a g2 - } - \addlyrics { twin -- kle twin -- kle lit -- tle star } ->> -@end lilypond - -Polyphonic notation and piano music can also be printed. The -following example combines some more exotic constructs. - -@lilypond[quote] -\header { - title = "Screech and boink" - subtitle = "Random complex notation" - composer = "Han-Wen Nienhuys" -} - -\score { - \context PianoStaff << - \new Staff = "up" { - \time 4/8 - \key c \minor - << { - \revert Stem #'direction - \change Staff = down - \set subdivideBeams = ##t - g16.[ - \change Staff = up - c'''32 - \change Staff = down - g32 - \change Staff = up - c'''32 - \change Staff = down - g16] - \change Staff = up - \stemUp - \set followVoice = ##t - c'''32([ b''16 a''16 gis''16 g''32)] - } \\ { - s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d''] - } \\ { - s4 \autoBeamOff d''8.. f''32 - } \\ { - s4 es''4 - } >> - } - - \new Staff = "down" { - \clef bass - \key c \minor - \set subdivideBeams = ##f - \override Stem #'french-beaming = ##t - \override Beam #'thickness = #0.3 - \override Stem #'thickness = #4.0 - g'16[ b16 fis16 g16] - << \makeClusters { - as16 - - - } \\ { - \override Staff.Arpeggio #'arpeggio-direction =#down - 4\arpeggio - } - >> } - >> - \midi { - \context { - \Score - tempoWholesPerMinute = #(ly:make-moment 60 8) - } - } - \layout { - \context { - \Staff - \consists Horizontal_bracket_engraver - } - } -} -@end lilypond - -The fragments shown above have all been written by hand, but that -is not a requirement. Since the formatting engine is mostly -automatic, it can serve as an output means for other programs that -manipulate music. For example, it can also be used to convert -databases of musical fragments to images for use on websites and -multimedia presentations. - -This manual also shows an application: the input format is text, -and can therefore be easily embedded in other text-based formats -such as @LaTeX{}, HTML, or in the case of this manual, Texinfo. -By means of a special program, the input fragments can be replaced -by music images in the resulting PDF or HTML output files. This -makes it easy to mix music and text in documents. - - @node About the documentation @section About the documentation diff --git a/Documentation/user/lily-flat-bw.png b/Documentation/user/lily-flat-bw.png deleted file mode 100644 index 09ce34e7c5..0000000000 Binary files a/Documentation/user/lily-flat-bw.png and /dev/null differ