From: Patrick McCarty Date: Thu, 9 Jul 2009 23:29:44 +0000 (-0700) Subject: Revert "Doc: move essay into its own manual." X-Git-Tag: release/2.13.4-1~366 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=7579b84d8172e7cadab8da3365742834cd6d1818;p=lilypond.git Revert "Doc: move essay into its own manual." This reverts commit 1af68220c260b8d17484dc283489541b1f9c74d3. --- diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index e8d3665d33..03a6a8a909 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 essay bibliography pictures topdocs misc po $(LANGS) +SUBDIRS=devel user 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 deleted file mode 100644 index 8d78ffe561..0000000000 --- a/Documentation/essay/GNUmakefile +++ /dev/null @@ -1,145 +0,0 @@ -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 deleted file mode 100644 index bb25bd1903..0000000000 Binary files a/Documentation/essay/baer-flat-bw.png and /dev/null differ diff --git a/Documentation/essay/baer-flat-gray.png b/Documentation/essay/baer-flat-gray.png deleted file mode 100644 index 08cd338380..0000000000 Binary files a/Documentation/essay/baer-flat-gray.png and /dev/null differ diff --git a/Documentation/essay/fdl.itexi b/Documentation/essay/fdl.itexi deleted file mode 100644 index 158e5c6c30..0000000000 --- a/Documentation/essay/fdl.itexi +++ /dev/null @@ -1,403 +0,0 @@ - -@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 deleted file mode 100644 index b47660f376..0000000000 Binary files a/Documentation/essay/henle-flat-bw.png and /dev/null differ diff --git a/Documentation/essay/henle-flat-gray.png b/Documentation/essay/henle-flat-gray.png deleted file mode 100644 index 20326b958a..0000000000 Binary files a/Documentation/essay/henle-flat-gray.png and /dev/null differ diff --git a/Documentation/essay/introduction.itely b/Documentation/essay/introduction.itely deleted file mode 100644 index 6ba3f550e4..0000000000 --- a/Documentation/essay/introduction.itely +++ /dev/null @@ -1,816 +0,0 @@ -@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 deleted file mode 100644 index 09ce34e7c5..0000000000 Binary files a/Documentation/essay/lily-flat-bw.png and /dev/null differ diff --git a/Documentation/essay/lilypond-essay.tely b/Documentation/essay/lilypond-essay.tely deleted file mode 100644 index 0e44ce80e8..0000000000 --- a/Documentation/essay/lilypond-essay.tely +++ /dev/null @@ -1,135 +0,0 @@ -\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 deleted file mode 100644 index 9dbf8a8ff3..0000000000 --- a/Documentation/essay/macros.itexi +++ /dev/null @@ -1,402 +0,0 @@ -@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 new file mode 100644 index 0000000000..bb25bd1903 Binary files /dev/null and b/Documentation/user/baer-flat-bw.png differ diff --git a/Documentation/user/baer-flat-gray.png b/Documentation/user/baer-flat-gray.png new file mode 100644 index 0000000000..08cd338380 Binary files /dev/null and b/Documentation/user/baer-flat-gray.png differ diff --git a/Documentation/user/henle-flat-bw.png b/Documentation/user/henle-flat-bw.png new file mode 100644 index 0000000000..b47660f376 Binary files /dev/null and b/Documentation/user/henle-flat-bw.png differ diff --git a/Documentation/user/henle-flat-gray.png b/Documentation/user/henle-flat-gray.png new file mode 100644 index 0000000000..20326b958a Binary files /dev/null and b/Documentation/user/henle-flat-gray.png differ diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index ab40eec69f..b031f13ab3 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -16,10 +16,804 @@ 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 new file mode 100644 index 0000000000..09ce34e7c5 Binary files /dev/null and b/Documentation/user/lily-flat-bw.png differ