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)"'
+++ /dev/null
-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:
+++ /dev/null
-
-@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:
-
+++ /dev/null
-@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 <e g b>4_>-\arpeggio
- \override Arpeggio #'direction = #RIGHT
- \stemUp <e g b>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
- <d f g>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
- <d f g>4
- \once \override NoteHead #'style = #'cross
- <d f g>4
- \applyOutput #'Voice #mc-squared
- <d f g>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
-<<c4 d4 e4>>
-@end example
-
-@lilypond[quote,fragment,relative=1]
-\new Voice { <<c4 d4 e>> }
-@end lilypond
-
-@noindent
-This expression is put in sequence by enclosing it in curly braces
-@code{@{@tie{}@dots{}@tie{}@}}:
-
-@example
-@{ f4 <<c4 d4 e4>> @}
-@end example
-
-@lilypond[quote,relative=1,fragment]
-{ f4 <<c d e4>> }
-@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 <<c4 d4 e4>> @} >>
-@end example
-
-@lilypond[quote,fragment,relative=2]
-\new Voice { << g2 \\ { f4 <<c d e>> } >> }
-@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 <as b>
- <g b>
- <g cis>
- } \\ {
- \override Staff.Arpeggio #'arpeggio-direction =#down
- <cis, e, gis, b, cis>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.
-
-
-
+++ /dev/null
-\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
+++ /dev/null
-@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
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 <e g b>4_>-\arpeggio
+ \override Arpeggio #'direction = #RIGHT
+ \stemUp <e g b>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
+ <d f g>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
+ <d f g>4
+ \once \override NoteHead #'style = #'cross
+ <d f g>4
+ \applyOutput #'Voice #mc-squared
+ <d f g>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
+<<c4 d4 e4>>
+@end example
+
+@lilypond[quote,fragment,relative=1]
+\new Voice { <<c4 d4 e>> }
+@end lilypond
+
+@noindent
+This expression is put in sequence by enclosing it in curly braces
+@code{@{@tie{}@dots{}@tie{}@}}:
+
+@example
+@{ f4 <<c4 d4 e4>> @}
+@end example
+
+@lilypond[quote,relative=1,fragment]
+{ f4 <<c d e4>> }
+@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 <<c4 d4 e4>> @} >>
+@end example
+
+@lilypond[quote,fragment,relative=2]
+\new Voice { << g2 \\ { f4 <<c d e>> } >> }
+@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 <as b>
+ <g b>
+ <g cis>
+ } \\ {
+ \override Staff.Arpeggio #'arpeggio-direction =#down
+ <cis, e, gis, b, cis>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
projects / lilypond.git / commitdiff
