+2004-08-28 Han-Wen Nienhuys <hanwen@xs4all.nl>
+
+ * Documentation/user/advanced.itely: removed.
+
+ * Documentation/user/programming-interface.itely (How markups work
+ internally): new subsection.
+
+ * Documentation/user/converters.itely (Invoking abc2ly): remove
+ musedata2ly.
+
2004-08-27 Han-Wen Nienhuys <hanwen@xs4all.nl>
* Documentation/user/point-and-click.texi (Point and click): new file.
+++ /dev/null
-@c UNUSED !! -*-texinfo-*-
-
-@node Advanced concepts
-@section Advanced concepts
-
-
-
-To understand this concept, imagine that you are performing a piece of
-music. When you are playing, you combine the symbols printed at a
-certain point with contextual information. For example, without
-knowing the current clef, and the accidentals in the last measure, it
-would be impossible to determine the pitch of a note. In other words,
-this information forms a context that helps you decipher a
-score. LilyPond produces notation from music, so in effect, it does
-the inverse of reading scores. Therefore, it also needs to keep track
-of contextual information. This information is maintained in
-``notation contexts.''
-
-****************
-
-Although LilyPond was designed to produce standard music notation, its
-architecture is flexible, and it is possible to manipulate the
-translation from a @file{.ly} file to a PDF file in many ways. This
-chapter discusses outlines the options for customization.
-
-Before we can explain what is possible, it it is necessary to
-understand the general architecture of LilyPond. The following
-diagram shows the different steps in producing a PDF file:
-
-@verbatim
-
- Parsing Interpretation Formatting
-
-.ly file -> Music -> Notation ->
-
-
- Formatting Dumping Titling
-
- -> Typography -> .tex -> .pdf file
-
-@end verbatim
-
-@enumerate
-
-@item @emph{Parsing} means reading a file, and translating letters and
- numbers into data structures.
-
-@item The central data structure is the @emph{Music} expression. It is
-the structure that stores music events (notes, chords, lyric
-syllables, etc.) and their combinations.
-
-@item In order to print a piece music, separate events have to be
-synchronized. For example, notes that sound together must be combined
-horizontally, while syllables must be combined on a line. This happens
-in the @emph{interpretating} step.
-
-@item The result of @emph{interpreting} is @emph{notation}, a
-collection of layout objects.
-
-@item The exact appearance of the layout objects is determined during
-@emph{formatting}. For example, in this step spacing and beam slopes
-are determined.
-
-@item After formatting, LilyPond dumps a @TeX{} file containing the
-symbols and their offsets.
-
-@item In a final step, titles are added to the music, resulting in a
-PostScript, DVI or PDF file.
-
-@end enumerate
-
-This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is
-discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in
-@ref{Invoking LilyPond}.
-
-The diagram above shows how music typesetting has been split-up in
-multiple subproblems. However, splitting up problems always produces
-the new problem of putting together the subsolutions to these
-subproblems. Therefore, we will start our advanced topics class with a
-discussion of the programming language Scheme, which lubricates the
-interactions between different modules of LilyPond.
-
-
-
-@section Scheme in LilyPond
-@node Scheme in LilyPond
-
-LilyPond includes an interpreter for the programming language Scheme,
-a member of the LISP family. This interpreter,
-@uref{http://www.gnu.org/software/guile/,GUILE},
-forms the basis of the
-
-****************************************************************
-
-@c -*-texinfo-*-
-@c Note:
-@c
-@c A menu is needed before every deeper *section nesting of @nodes
-@c Run M-x texinfo-all-menus-update
-@c to automatically fill in these menus
-@c before saving changes
-
-
-@node Technical manual
-@chapter Technical manual
-
-
-When LilyPond is run, it reads music from a file, translates that into
-notation, and outputs the result to a file. The most important steps
-are the first three. Consequently, there are three important basic
-concepts within LilyPond: music, translation and layout. The
-following diagram illustrates the concepts, and list the terminology
-associated with each step.
-
-
-@verbatim
-
- +-------------+ Translation +----------+
- | | | |
- | Music | ------------------> | Layout |
- | | | |
- +-------------+ +----------+
-
-
-Syntax: c4 \context \set #'padding =
- \override
-
-Objects: Music expressions Contexts Layout object
- Engravers (aka. Grob)
-
-Example objects: NoteEvent Voice NoteHead
- Note_heads_engraver
-
-Example properties: #'pitch keySignature #'line-count
-
-User applications: none various tuning layout
-
-@end verbatim
-
-The objects passed around in LilyPond have @emph{properties},
-variables that can contain many different types of information. Users
-can set these variables, to modify the default behavior. Since there
-are three different main concepts, there are also three types of
-properties:
-
-@cindex properties
-@cindex concepts, main
-@cindex context
-@cindex music expressions
-@cindex layout
-@cindex grob
-
-
-@table @b
-@item Music properties
-These are used internally, and most users will not see or use them.
-
-They use Scheme-style naming, i.e. lowercase words separated with
-dashes: @code{pitch}, @code{tremolo-type}.
-
-@item Translation properties
-These influence the translation process, and most users will encounter them
-regularly. For example, beaming behavior is tuned with
-@code{autoBeamSettings}.
-
-These use mixed-caps naming: @code{autoBeamSettings},
-@code{ignoreMelismata}. They are assigned as follows:
-@example
- \set ignoreMelismata = ...
-@end example
-
-@item Layout properties
-These are internally used in the formatting process. Consequently, to
-tune formatting details, it is necessary to adjust these
-properties. For example, some objects may be moved around vertically
-by setting their @code{padding} property.
-
-These properties use Scheme-style naming: @code{c0-position},
-@code{break-align-symbol}. They most often assigned as follows:
-
-@example
- \override Score.RehearsalMark #'break-align-symbol = ...
-@end example
-
-@noindent
-Here, @code{RehearsalMark} is the type of the layout object.
-
-@end table
-
* Vertical spacing of piano staves::
* Vertical spacing::
* Horizontal spacing::
+* Line length::
* Line breaking::
-* Line length and line breaking::
* Multiple movements::
-* Titling::
+* Creating titles::
* Page breaking::
* Paper size::
* Page layout::
* Invoking midi2ly:: Importing MIDI.
* Invoking etf2ly:: Importing Finale.
* Invoking abc2ly:: Importing ABC.
-* Invoking musedata2ly:: Importing Musedata.
* Invoking mup2ly:: Importing MUP.
@end menu
@node Invoking convert-ly
@section Invoking convert-ly
-Convert-ly sequentially applies different conversions to upgrade a
-LilyPond input file. It uses @code{\version} statements in the file to
-detect the old version number. For example, to upgrade all LilyPond
-files in the current directory and its subdirectories, use
+The syntax is regularly changed to simplify it or improve it in
+different ways. A side effect of this, is that LilyPond often is not
+compatible with older files. To remedy this, the program convert-ly
+can be used to deal with most of the syntax changes.
+
+It uses @code{\version} statements in the file to detect the old
+version number. For example, to upgrade all LilyPond files in the
+current directory and its subdirectories, enter the following on the
+command line.
+
@example
convert-ly -e --to=1.3.150 `find . -name '*.ly' -print`
@end example
instruments: it specifies cabling, a serial protocol and a file
format. The MIDI file format is a de facto standard format for
exporting music from other programs, so this capability may come in
-useful when you want to import files from a program that has no
-converter for its native format.
+useful when importing files from a program that has convertor for a
+direct format.
Midi2ly will convert tracks into @internalsref{Staff} and
channels into @internalsref{Voice} contexts. Relative mode is used
It is possible to record a MIDI file using a digital keyboard, and
then convert it to @file{.ly}. However, human players are not
rhythmically exact enough to make a MIDI to LY conversion trivial.
-midi2ly tries to compensate for these timing errors, but is not very
-good at this. It is therefore not recommended to use midi2ly for
+When invoked with quantizing (@code{-s} and @code{-d} options) midi2ly
+tries to compensate for these timing errors, but is not very good at
+this. It is therefore not recommended to use midi2ly for
human-generated midi files.
-Hackers who know about signal processing are invited to write a more
-robust midi2ly. midi2ly is written in Python, using a module written in
-C to parse the MIDI files.
It is invoked as follows:
@example
@refbugs
-
-Quantizing start-times and durations should be recommended.
-This relates to the notes regarding the transcription of a MIDI
-recording of a performance. I realize it can be done via the utility,
-but a sequencer gives better visual feedback.
-
-Overlapping notes in an arpeggio will not be correctly
-rendered. The first note will be read and the others will be ignored.
-Set them all to a single duration and add phrase markings or pedal
-indicators.
+Overlapping notes in an arpeggio will not be correctly rendered. The
+first note will be read and the others will be ignored. Set them all
+to a single duration and add phrase markings or pedal indicators.
@node Invoking etf2ly
@refbugs
-The list of articulation scripts is incomplete. Empty measures confuse
-etf2ly. Sequences of grace notes are ended improperly sometimes.
+The list of articulation scripts is incomplete. Empty measures
+confuse etf2ly. Sequences of grace notes are ended improperly.
@node Invoking abc2ly
abc2ly ignores the ABC beaming.
-@node Invoking musedata2ly
-@section Invoking musedata2ly
-
-@cindex MuseData
-@cindex CCARH
-
-@uref{http://www.musedata.org/,MuseData} is an electronic library of
-classical music scores, comprising at the time of writing about 800
-composition dating from 1700 to 1825. The music is encoded in
-so-called MuseData format. musedata2ly converts a set of MuseData
-files to one .ly file, and will include a @code{\header} field if a
-@file{.ref} file is supplied. It is invoked as follows:
-
-@example
- musedata2ly [@var{option}]@dots{} @var{musedata-files}
-@end example
-
-The following options are supported by musedata2ly:
-
-@table @code
-@item -h,--help
-print help
-@item -o,--output=@var{file}
-set output filename to @var{file}
-@item -v,--version
-version information
-@item -r,--ref=@var{reffile}
- read background information from ref-file
-@var{reffile}
-@end table
-
-@refbugs
-
-@file{musedata2ly} converts only a small subset of MuseData.
@node Invoking mup2ly
@section Invoking mup2ly
@ifhtml
The chapter
@end ifhtml
-@emph{@ref{Invoking LilyPond}} shows how to run LilyPond and its helper
+@emph{@ref{Running LilyPond}} shows how to run LilyPond and its helper
programs.
@item
@c -*-texinfo-*-
-@node Invoking LilyPond
-@chapter Invoking LilyPond
+@node Running LilyPond
+@chapter Running LilyPond
This chapter details the technicalities of running LilyPond.
If you have input that results in a crash or an erroneous output, then
that is a bug. We try respond to bug-reports promptly, and fix them as
-soon as possible. For this, we need to reproduce and isolate the
-problem. Help us by sending a defective input file, so we can
+soon as possible. Help us by sending a defective input file, so we can
reproduce the problem. Make it small, so we can easily debug the
problem. Don't forget to tell which version you use, and on which
platform you run it. Send the report to
@table @asis
@item Emacs
- Emacs has a @file{lilypond-mode}, which provides keyword
+Emacs has a @file{lilypond-mode}, which provides keyword
autocompletion, indentation, LilyPond specific parenthesis matching
and syntax coloring, handy compile short-cuts and reading LilyPond
-manuals using Info. If lilypond-mode is not installed on your
-platform, then refer to the installation instructions for more
-information.
+manuals using Info. If @file{lilypond-mode} is not installed on your
+platform, then read the
+@ifhtml
+@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
+@end ifhtml
+@ifnothtml
+installation instructions.
+@end ifnothtml
+for more information.
@item VIM
-For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
+For @uref{http://www.vim.org,VIM}, a @file{vimrc} is supplied, along with
syntax coloring tools. For more information, refer to the
@ifhtml
@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
@end ifnothtml
-For both editors, there is also a facility to jump in the input file
-to the source of errors in the graphical output. See @ref{Point and
-click}.
-
@item JEdit
There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
@end table
+For both VIM and Emacs editors, there is also a facility to jump in
+the input file to the source of errors in the graphical output. See
+@ref{Point and click}.
+
adjusted to match the layout of your document.
This procedure may be applied to La@TeX{}, @code{html} or Texinfo
-documents. A tutorial on using lilypond-book is in @ref{Integrating
-text and music}. For more information about La@TeX{}
-@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
-Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
+documents.
@cindex documents, adding music to
-@node Integrating Texinfo and music
-@section Integrating Texinfo and music
-
-Music is specified like this:
-
-@example
-@@lilypond[options,go,here]
- YOUR LILYPOND CODE
-@@end lilypond
-@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@@lilypondfile[options,go,here]@{@var{filename}@}
-@end example
-
-When lilypond-book is run on it, this results in a texinfo file. We
-show two simple examples here. First a complete block:
-
-@example
-@@lilypond[staffsize=26]
- c' d' e' f' g'2 g'
-@@end lilypond
-@end example
-
-@noindent
-produces
-
-@lilypond[fragment]
- c' d' e' f' g'2 g'
-@end lilypond
-
-Then the short version:
-
-@example
-@@lilypond[staffsize=11]@{<c' e' g'>@}
-@end example
-
-@noindent
-produces
-
-@lilypond[fragment,staffsize=11]{ <c' e' g'> }
-
-When producing texinfo, lilypond-book also generates bitmaps of the
-music, so you can make a HTML document with embedded music.
-
@c @TeX{} in node name seems to barf
@node Integrating LaTeX and music
@section Integrating LaTeX and music
+La@TeX{} is the de facto standard for publishing papers in the exact
+sciences. It is built on top of the @TeX{} typesetting engine, so it
+provides the best typography available anywhere.
+
+For more information about La@TeX{}
+@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
+Short Introduction to La@TeX{}} provides a introduction to using
+La@TeX{}.
For La@TeX{}, music is entered using
The linewidth of the music will be adjust by examining the commands in
the document preamble, the part of the document before
-@code{\begin@{document@}}: @command{lilypond-book} sends these to
-La@TeX{} to find out how wide the text is. The line width variable for
-the music fragments are adjusted to the text width.
+@code{\begin@{document@}}. The @command{lilypond-book} command sends
+these to La@TeX{} to find out how wide the text is. The line width
+for the music fragments is then adjusted to the text width.
After @code{\begin@{document@}}, the column changing commands
@code{\onecolumn}, @code{\twocolumn} commands
@cindex dvips
@cindex invoking dvips
-For printing the LaTeX document, you will need to use dvips. For
+For printing the La@TeX{} document, you will need to use dvips. For
producing PostScript with scalable fonts, add the following options to
the dvips command line:
@example
@cindex international characters
@cindex latin1
-LilyPond does not use the LaTeX font handling scheme for lyrics and text
+LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
markups, so if you use characters in your lilypond-book
documents that are not included in the standard US-ASCII character set,
include @code{\usepackage[latin1]@{inputenc@}} in the file
-header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
+header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
sets other than latin1 are not supported directly but may be handled by
explicitly specifying the @code{font-name} property in LilyPond and
-using the corresponding LaTeX packages. Please consult the mailing list
+using the corresponding La@TeX{} packages. Please consult the mailing list
for more details.
+@node Integrating Texinfo and music
+@section Integrating Texinfo and music
+
+Texinfo is the standard format for documentation at the GNU
+project. An example of a texinfo document is this manual. The HTML,
+PDF and Info versions of the manual are made from the document.
+
+When run on a lilypond-book, produces a @file{.texi} file containing
+@code{@@image} tags for HTML and info. For the printed edition, the
+raw @TeX{} output of LilyPond is included into the main document.
+
+In the input file, music is specified like
+
+@example
+@@lilypond[options,go,here]
+ YOUR LILYPOND CODE
+@@end lilypond
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@@lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+When lilypond-book is run on it, this results in a texinfo file. We
+show two simple examples here. First a complete block:
+
+@example
+@@lilypond[staffsize=26]
+ c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment]
+ c' d' e' f' g'2 g'
+@end lilypond
+
+Then the short version:
+
+@example
+@@lilypond[staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment,staffsize=11]{ <c' e' g'> }
+
+When producing texinfo, lilypond-book also generates bitmaps of the
+music, so you can make a HTML document with embedded music.
+
+
+
+
@node Integrating HTML and music
@section Integrating HTML and music
prevents printing time signature.
@item fragment
-@item nofragment
-overrides @command{lilypond-book} auto detection of what type of code is
-in the LilyPond block, voice contents, or complete code.
+adds some boilerplate code, so you can enter like
+
+@example
+ c'4
+@end example
+
+@noindent
+without @code{\paper}, @code{\score} or other red tape.
@item indent=@var{size}\@var{unit}
sets indentation of the first music system to @var{size},
For example:
@example
- lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
+ lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
@end example
@item @option{--help}
@section Bugs
-The La@TeX{} @code{\includeonly@{...@}} command is ignored.
-
The Texinfo command @code{pagesize} is not interpreted. Almost all
La@TeX{} commands that change margins and line widths are ignored.
@c prepend GNU for dir, must be unique
@c do not list the `lilypond' node at toplevel, so that `info lilypond'
@c goes to Top.
-@c * lilypond: (lilypond/lilypond)Invoking LilyPond. Titling LilyPond scores.
+@c * lilypond: (lilypond/lilypond)Running LilyPond. Invoking the
+@c LilyPond program.
* GNU LilyPond: (lilypond/lilypond). The GNU music typesetter.
* convert-ly: (lilypond/lilypond)Invoking convert-ly. Older LilyPond versions.
* midi2ly: (lilypond/lilypond)Invoking midi2ly. Importing MIDI.
* Sound:: Producing MIDI output
* Changing defaults:: Tuning output.
* Interfaces for programmers::
-* Invoking LilyPond:: Operation.
+* Running LilyPond:: Operation.
* Converting from other formats:: Converting to lilypond source format.
* Integrating text and music:: Integrating text and music with lilypond-book.
* Literature list::
@appendix Literature list
If you need to know more about music notation, here are some
-interesting titles to read. The source archive includes a more
-elaborate Bib@TeX{} bibliography of over 100 entries in
-@file{Documentation/bibliography/}. It is also available online from
-the website.
+interesting titles to read.
+
+
@table @cite
@item Ignatzek 1995
practices.
@end table
+
+The source archive includes a more elaborate Bib@TeX{} bibliography of
+over 100 entries in @file{Documentation/bibliography/}. It is also
+available online from the website.
@node Chord name chart
@appendixsec Chord name chart
+The following charts shows two standard systems for printing chord
+names, along with the pitches they represent.
+
@lilypondfile{chord-names-jazz.ly}
@node MIDI instruments
@appendixsec MIDI instruments
+The following is a list of names that can be used for the
+@code{midiInstrument} property.
+
@example
"acoustic grand" "contrabass" "lead 7 (fifths)"
"bright acoustic" "tremolo strings" "lead 8 (bass+lead)"
"dulcimer" "tuba" "fx 6 (goblins)"
"drawbar organ" "muted trumpet" "fx 7 (echoes)"
"percussive organ" "french horn" "fx 8 (sci-fi)"
-"rock organ" "brass appendixsection" "sitar"
+"rock organ" "brass section" "sitar"
"church organ" "synthbrass 1" "banjo"
"reed organ" "synthbrass 2" "shamisen"
"accordion" "soprano sax" "koto"
* Input variables and Scheme::
* Internal music representation::
* Extending music syntax::
-* Manipulating music expressions::
-* Using LilyPond syntax inside Scheme::
+* Manipulating music expressions::
+* Using LilyPond syntax inside Scheme::
@end menu
@node Input variables and Scheme
In the above example, music expressions can be `exported' from the
input to the Scheme interpreter. The opposite is also possible. By
wrapping a Scheme value in the function @code{ly:export}, a Scheme
-value is interpreted as if it were entered in LilyPond syntax: instead
+value is interpreted as if it were entered in LilyPond syntax. Instead
of defining @code{\twice}, the example above could also have been
written as
@example
@refbugs
-Mixing Scheme and lily identifiers is not possible with @code{--safe}.
+Mixing Scheme and LilyPond identifiers is not possible with the
+@code{--safe} option.
@node Internal music representation
@subsection Internal music representation
music object in the @code{element} object. For example,
@internalsref{SequentialMusic} has its children in @code{elements},
and @internalsref{GraceMusic} has its single argument in
-@code{element}. The body of a repeat is in @code{element} property of
-@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
+@code{element}. The body of a repeat is stored in the @code{element}
+property of @internalsref{RepeatedMusic}, and the alternatives in
+@code{elements}.
functions:
@example
- applymusic = #(def-music-function (location func music) (procedure? ly:music?)
+ applymusic = #(def-music-function (location func music)
+ (procedure? ly:music?)
(func music))
@end example
@code{ly:music-set-property!}.
An example is a function that reverses the order of elements in
-its argument:
+its argument,
@lilypond[verbatim,raggedright]
#(define (rev-music-1 m)
(ly:music-set-property! m 'elements (reverse
The use of such a function is very limited. The effect of this
function is void when applied to an argument which is does not have
-multiple children. The following function application has no effect:
+multiple children. The following function application has no effect
@example
\applymusic #rev-music-1 \grace @{ c4 d4 @}
@noindent
In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
@code{elements}, only a single @code{element}. Every generally
-applicable function for @code{\applymusic} must -- like music expressions
+applicable function for @code{\applymusic} must---like music expressions
themselves -- be recursive.
The following example is such a recursive function: It first extracts
@node Markup programmer interface
@section Markup programmer interface
+Markups implemented as special Scheme functions. When applied with as
+arguments an output definition (@code{\paper} or @code{\bookpaper}),
+and a list of properties and other arguments, produce a Stencil
+object.
@menu
* Markup construction in scheme::
+* How markups work internally ::
* Markup command definition::
@end menu
@end lisp
is illegal. One should use the @code{make-line-markup} (resp
@code{make-center-markup}, @code{make-column-markup}) function
-instead:
+instead,
@lisp
(markup (make-line-markup (fun-that-returns-markups)))
@end lisp
+@node How markups work internally
+@subsection How markups work internally
+
+In a markup like
+
+@example
+ \raise #0.5 "foo"
+@end example
+
+@noindent
+@code{\raise} is actually represented by the @code{raise-markup}
+function. The markup expression is stored as
+
+@example
+ (list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
+@end example
+
+@noindent
+In this case, @code{latin1} is the input encoding, which is set with
+the @code{\encoding} command.
+
+When the markup is converted to printable objects (Stencils), the
+raise markup is called as
+
+@example
+ (apply raise-markup
+ @var{\paper object}
+ @var{list of property alists}
+ 0.5
+ @var{the "foo" markup})
+@end example
+
+The @code{raise-markup} first creates the stencil for the @code{foo}
+string, and then it raises that Stencil by 0.5 staff space. This is a
+rather simple example; more complex examples are in the rest of this
+section, and in @file{scm/define-markup-commands.scm}.
+
@node Markup command definition
@subsection Markup command definition
@menu
* First steps::
-* Running LilyPond::
+* Running LilyPond for the first time::
* More about pitches::
* Entering ties::
* Automatic and manual beams::
@end quotation
-@node Running LilyPond
-@section Running LilyPond
+@node Running LilyPond for the first time
+@section Running LilyPond for the first time
+
+@c cheesy title to avoid clash with chapter name.
@c FIXME: let's not be so casual about Emacs and VIM, but rather
@c instruct (how) to use them; let advanced user figure-out what
When the file is processed the title and composer are printed above
-the music. More information on titling can be found in @ref{Titling}.
+the music. More information on titling can be found in @ref{Creating
+titles}.
@node Single staff polyphony
## prevent TeX from interpreting "--" as long dash:
tex_string=re.sub('--','-{}-', tex_string)
- file.write (' \\markup { \\raise #0.75 \\vcenter \\musicglyph #"%s" " %s" } 4 \n' % (scm_string, tex_string))
+ file.write (' \\markup { \\raise #0.75 \\vcenter \\musicglyph #"%s" \\typewriter " %s" } 4 \n' % (scm_string, tex_string))
if (count % 3) ==0:
file.write ('\skip 8 \\break\n')
@item laziness
Over how many bar lines the accidental lasts.
-If @var{laziness} is @code{-1} then the accidental is forget
+If @var{laziness} is @code{-1} then the accidental is forgotten
immediately, and if @var{laziness} is @code{#t} then the accidental
lasts forever.
@end table
(chordRootNamer ,procedure?
"Function that converts from a pitch object to a text markup. Used for chords.")
(chordNameExceptions ,list?
- "Alist of chord exceptions.
+ "An alist of chord exceptions.
Contains (@var{chord} . @var{markup}) entries.")
(chordNameExceptionsFull ,list?
- "Alist of chord exceptions.
+ "An alist of chord exceptions.
Contains (@var{chord} . @var{markup}) entries.")
(chordNameExceptionsPartial
,list?
- "Alist of partial chord exceptions. Contains (@var{chord} . (@var{prefix-markup} @var{suffix-markup})) entries.")
+ "An alist of partial chord exceptions. Contains (@var{chord} . (@var{prefix-markup} @var{suffix-markup})) entries.")
(chordNameSeparator ,markup?
"The markup object used to separate
(connectArpeggios ,boolean? " If set, connect arpeggios across
piano staff.")
(createKeyOnClefChange ,boolean? "Print a key signature whenever the clef is changed.")
- (createSpacing ,boolean? "Create StaffSpacing objects? Should be set for staves.")
+ (createSpacing ,boolean? "Create @code{StaffSpacing} objects?
+Should be set for staves.")
(crescendoText ,markup? "Text to print at start of non-hairpin crescendo, i.e.: @samp{cresc.}")
(crescendoSpanner ,symbol? "Type of spanner to be used for crescendi.
One of: @samp{hairpin}, @samp{line}, @samp{dashed-line},
(explicitKeySignatureVisibility ,procedure?
"@samp{break-visibility} function for explicit key
-changes. @samp{\\override} of @samp{#'break-visibility} will set the
+changes. @samp{\\override} of the @code{break-visibility} property will set the
visibility for normal (i.e. at the start of the line) key signatures.")
(extraNatural ,boolean? "Whether to typeset an
"extra vertical extent, same format as @var{minimumVerticalExtent}")
- (followVoice ,boolean? "if set, note heads are tracked across staff
+ (followVoice ,boolean? "If set, note heads are tracked across staff
switches by a thin line")
(fontSize ,number?
(keyAccidentalOrder ,list? " Alist that defines in what order
alterations should be printed. The format is (@var{name}
-. @var{alter}), where @var{name} is from 0 .. 6 and @var{alter} from -1, 1.
+. @var{alter}), where @var{name} is from 0 .. 6 and @var{alter} from
+-2 (sharp) and 2 (flat).
")
(keySignature ,list? "The current key signature. This is an alist
(midiMinimumVolume ,number? "Sets the minimum loudness for MIDI. Ranges from 0 to 1.")
(midiMaximumVolume ,number? "Analogous to @code{midiMinimumVolume}.")
(minimumFret ,number? "The tablature auto string-selecting mechanism
-selects the highest string with a fret at least @var{minimumFret}")
+selects the highest string with a fret at least @code{minimumFret}")
(minimumVerticalExtent ,number-pair? "minimum vertical extent, same
format as @var{verticalExtent}")
(ottavation ,string? "If set, the text for an ottava spanner. Changing
+++ /dev/null
-#!@PYTHON@
-
-# musedata = musedata.stanford.edu
-# musedata = COBOL for musicians.
-
-
-# TODO
-#
-# * clefs,
-# * keys,
-# * staffs,
-# * multiple voices (they use `Backspace' (shudder)
-# * tuplets
-#
-
-#
-# I completely forgot how this was supposed to work --hwn 5/2002
-#
-#
-
-import re
-import sys
-import string
-import getopt
-import os
-program_name = 'musedata2ly'
-version = '@TOPLEVEL_VERSION@'
-if version == '@' + 'TOPLEVEL_VERSION' + '@':
- version = '(unknown version)' # uGUHGUHGHGUGH
-
-
-
-ref_header_dict = {
- 'COM': 'composer',
- 'OPR': 'collection',
- 'OTL': 'title',
- 'OMV': 'subtitle',
- 'YOR': 'source',
- 'AGN': 'instrument',
- 'END': 'encodingdate',
- 'CDT': 'date',
- 'OCY': 'composedin',
- 'AST': 'genre',
- 'YEC': 'copyright',
- 'YEM': 'license',
- 'YEN': 'encodingcountry',
- 'EED': 'editor',
- 'SCA': 'opus',
- 'ONM': 'onm',
- 'ENC': 'musedataencoder',
- 'KEY': 'musedatakey',
- 'AFT': 'musedatastage'
- }
-
-
-class Ref_parser:
- def __init__ (self, fn):
- self.dict = {}
-
- ls = open (fn).readlines ()
- self.parse (ls)
- def parse (self,ls):
- for l in ls:
- m = re.match('!!!([A-Z]+):[ \t]+(.*)$',l)
- if m:
- key = m.group(1)
- val = m.group (2)
- val = re.sub ('[ \t]+', ' ', val)
- try:
-
- key =ref_header_dict [key]
- except KeyError:
- sys.stderr.write ('\nUnknown ref key \`%s\'' % key)
- s = ''
- try:
- s = self.dict[key]
- except KeyError:
- pass
-
- s = s + val
- self.dict[key] = s
- def dump( self):
- str = ''
- for (k,v) in self.dict.items ():
- str = str +' %s = "%s"\n' % (k,v)
- str = '\\header {\n%s}' % str
- return str
-
-verbose = 0
-
-
-actab = {-2: 'eses', -1: 'es', 0 : '', 1: 'is', 2:'isis'}
-
-def pitch_to_lily_string (tup):
- (o,n,a) = tup
-
- nm = chr((n + 2) % 7 + ord ('a'))
- nm = nm + actab[a]
- if o > 0:
- nm = nm + "'" * o
- elif o < 0:
- nm = nm + "," * -o
- return nm
-
-def get_key (s):
- i = string.atoi (s)
- return ''
-
-def get_timesig (s):
- return '\\time %s\n' % s
-
-
-divisions = 4
-def get_divisions_per_quarter (s):
- divisions = string.atoi (s)
- return ''
-
-def get_directive (s):
- return '%% %s\n' % s
-
-def get_transposing (s):
- return ''
-
-def get_num_instruments (s):
- return ''
-
-def get_lilypond_notename (p, ac):
- if p > 5:
- p = p - 7
- s = chr (p + ord ('c'))
- infix = 'i'
- if ac < 0:
- infix = 'e'
- ac = -ac
-
- while ac:
- s = s + infix + 's'
- ac = ac - 1
- return s
-def get_clef ():
- return ''
-
-SPACES = ' '
-DIGITS = "0123456789"
-
-
-clef_dict = {
-04: 'treble',
-13 : 'alto',
-22: 'bass',
-}
-attr_dict = {
- 'C' : get_clef,
- 'K' : get_key ,
- 'T' : get_timesig,
- 'Q' : get_divisions_per_quarter,
- 'D' : get_directive,
- 'X' : get_transposing,
- 'I': get_num_instruments,
- }
-
-class Attribute_set:
- def __init__ (self, dict):
- self.dict = dict
- def dump (self):
- s = ''
- if self. dict.has_key ('T'):
- s = s+ get_timesig (self.dict['T'])
-
- return s
-
-
-script_table = {
-'v': '\\upbow',
-'n': '\\downbow',
-'o': '\\harmonic',
-'0': '"openstring',
-'Q': '\\thumb',
-'>': '^',
-'V': '^',
-'.': '.',
-'_': '-',
-'=': '"det leg"',
-'i': '|',
-'s': '"\\\\textsharp"',
-'n': '"\\\\textnatural"',
-'b': '"\\\\textflat"',
-'F': '\\fermata',
-'E': '\\fermata',
-}
-
-
-class Chord:
- def __init__ (self):
- self.pitches = []
- self.grace = 0
- self.cue = 0
- self.slurstart = []
- self.slurstop = []
- self.scripts = []
- self.syllables = []
- self.dots = 0
- self.basic_duration = 4
- self.tied = 0
-
- self.note_suffix = self.note_prefix = ''
- self.chord_suffix = self.chord_prefix = ''
-
- def add_script (self,s):
- self.scripts.append (s)
- def set_duration (self, d):
- self.basic_duration = d
- def add_syllable (self, s):
- self.syllables.append (s)
- def add_pitch (self,t):
- self.pitches.append (t)
-
- def dump (self):
- str = ''
-
- sd = ''
- if self.basic_duration == 0.5:
- sd = '\\breve'
- else:
- sd = '%d' % self.basic_duration
-
- sd = sd + '.' * self.dots
-
- for p in self.pitches:
- if str:
- str = str + ' '
- str = str + pitch_to_lily_string (p)
-
- if len (self.pitches) > 1:
- str = '<%s>' % str
- elif len (self.pitches) == 0:
- str = 'r'
-
- str = str + sd + '(' * len (self.slurstart) + ')' * len (self.slurstart)
- for s in self.scripts:
- str = str + '-' + s
-
- str = self.note_prefix +str + self.note_suffix
- str = self.chord_prefix + str + self.chord_suffix
- return str
-
-class Measure_start:
- def dump (self):
- return ' |\n'
-
-class Parser:
- def append_entry (self, e):
- self.entries.append (e)
- def append_chord (self,c ):
- self.chords.append (c)
- self.entries.append (c)
- def last_chord (self):
- return self.chords[-1]
- def __init__ (self, fn):
- self.divs_per_q = 1
- self.header_dict = {
- 'tagline' :'automatically converted from Musedata',
- 'copyright' : 'all rights reserved -- free for noncommercial use'
- # musedata license (argh)
- }
- self.entries = []
- self.chords = []
-
-
- lines = open (fn).readlines ()
- lines = map (lambda x: re.sub ("\r$", '', x), lines)
- lines = self.parse_header (lines)
- lines = self.append_lines (lines)
- str = string.join (lines, '\n')
- lines = re.split ('[\n\r]+', str)
- self.parse_body (lines)
-
- def parse_header (self, lines):
- enter = string.split (lines[3], ' ')
- self.header_dict['enteredby'] = string.join (enter[1:])
- self.header_dict['enteredon'] = enter[0]
- self.header_dict['opus'] = lines[4]
- self.header_dict['source'] = lines[5]
- self.header_dict['title'] = lines[6]
- self.header_dict['subtitle'] = lines[7]
- self.header_dict['instrument']= lines[8]
- self.header_dict['musedatamisc'] =lines[9]
- self.header_dict['musedatagroups'] =lines[10]
- self.header_dict['musedatagroupnumber']=lines[11]
- lines = lines[12:]
- comment = 0
- while lines:
- if lines[0][0] == '$':
- break
- lines = lines[1:]
- return lines
-
- def parse_musical_attributes (self,l):
- atts = re.split('([A-Z][0-9]?):', l)
- atts = atts[1:]
- found = {}
- while len (atts):
- id = atts[0]
- val = atts[1]
- atts = atts[2:]
- found[id] = val
-
- try:
- self.divs_per_q = string.atoi (found['Q'])
- except KeyError:
- pass
-
- self.append_entry (Attribute_set (found))
- def append_entry (self, e):
- self.entries.append (e)
-
- def parse_line_comment (self,l):
- pass
-
- def parse_note_line (self,l):
- ch = None
- if verbose:
- print DIGITS+DIGITS+DIGITS
- print l
- pi = l[0:5]
- di = l[5:8]
- tied = l[8:9] == '-'
-
- cue = grace = 0
- if (pi[0] == 'g'):
- grace = 1
- pi = pi[1:]
- elif (pi[0] == 'c'):
- cue = 1
- pi = pi[1:]
-
- if pi[0] == ' ':
- ch = self.last_chord ()
- pi = pi[1:]
- else:
- ch = Chord ()
- self.append_chord (ch)
-
-
- ch.cue = ch.cue or cue
- ch.grace = ch.grace or grace
-
- while pi[0] in SPACES:
- pi = pi[1:]
-
- if pi[0] <> 'r':
- name = ((ord (pi[0]) -ord('A')) + 5) % 7
- alter = 0
- pi = pi[1:]
- while pi and pi[0] in '#f':
- if pi[0] == '#':
- alter = alter + 1
- else:
- alter = alter - 1
- pi = pi[1:]
-
- oct = string.atoi (pi) - 3
-
- pittup = (oct, name ,alter)
- ch.add_pitch (pittup)
-
- ch.dots = 0
-
- dot_str = l[17:18]
- if dot_str == '.':
- ch.dots = 1
- elif dot_str == ':':
- ch.dots = 2
-
- base_dur = None
- if ch.cue or ch.grace:
- c = di[2]
- if c == '0':
- ch.accaciatura = 1
- elif c == 'A':
- base_dur = 0.5
- else:
- base_dur = 1 << (9 - (ord (c) - ord ('0')))
- else:
- fact = (1,1)
- if ch.dots == 1:
- fact = (2,3)
- elif ch.dots == 2:
- fact = (4, 7)
-
- base_dur = (4 * self.divs_per_q* fact[1]) / (string.atoi (di)* fact[0])
- ch.set_duration (base_dur)
-
- ch.tied = ch.tied or tied
-
- if l[26:27] == '[':
- ch.start_beam = 1
- elif l[26:27] == ']':
- ch.end_beam = 1
-
-
- additional = l[32:44]
- for c in additional:
- if c in '([{z':
- ch.slurstart.append( 0)
- continue
- elif c in ')]}x':
- ch.slurstop.append( 0)
- continue
-
- if c == '*':
- ch.start_tuplet = 1
- continue
- elif c == '!':
- ch.stop_tuplet = 1
- continue
-
- if c in DIGITS:
- ch.add_script (c)
- continue
-
- if c == ' ' :
- continue
-
- try:
- scr = script_table[c]
- ch.add_script (scr)
- c = None
- except KeyError:
- sys.stderr.write ("\nFixme: script `%s' not done\n" % c)
-
- text = l[40:81]
- sylls = string.split (text,'|')
-
- for syl in sylls:
- ch.add_syllable (syl)
-
-
- def parse_measure_line (self,l):
- self.append_entry (Measure_start())
-
-
- def parse_duration (l):
- s = ''
- while l[0] in '0123456789':
- s = s + l[0]
- l= l[1:]
- print l
- num = string.atoi (s)
- den = 4 * divisions
-
- current_dots = 0
- try_dots = [3, 2, 1]
- for d in try_dots:
- f = 1 << d
- multiplier = (2*f-1)
- if num % multiplier == 0 and den % f == 0:
- num = num / multiplier
- den = den / f
- current_dots = current_dots + d
-
- if num <> 1:
- sys.stderr.write ('huh. Durations left')
- return '%s%s' % (den, '.' * current_dots)
-
- def append_lines (self,ls):
- nls = []
- for l in ls:
- if l[0] == 'a':
- nls[-1] = nls[-1]+l[1:]
- else:
- nls.append(l)
- return nls
- def dump (self):
- s = ''
- ln = ''
- for e in self.entries:
-
- next = ' ' + e.dump()
- if len (ln) + len (next) > 72:
- s = s +ln + '\n'
- ln = ''
- ln = ln + next
-
- s = s + ln
-
- s = '\\notes {\n %s \n}' % s
- return s
-
- def parse_body (self,lines):
- comment_switch = 0
- for l in lines:
- if not l:
- continue
-
- c = l[0]
- if c == '&':
- comment_switch = not comment_switch
- continue
-
- if comment_switch:
- continue
-
- if 0:
- pass
- elif c == '$':
- self.parse_musical_attributes (l)
- elif c == '@':
- self.parse_line_comment (l)
- elif c == '*':
- self.parse_musical_directions (l)
- elif c in 'ABCDEFGr ':
- self.parse_note_line (l)
- elif c == 'm':
- self.parse_measure_line (l)
- elif c == '/':
- break
- elif c in 'PS':
- pass # ignore sound & print
- else:
- sys.stderr.write ("\nUnrecognized record `%s'\n"% l)
-
-
-
-
-
-def help ():
- sys.stdout.write (
-"""Usage: musedata2ly [OPTIONS]... FILE1 [FILE2 ...]
-
-Convert musedata to LilyPond.
-
-Options:
- -h,--help print this help
- -o,--output=FILE set output filename to FILE
- -v,--version show version information
- -r,--ref=REF read background information from ref-file REF
-
-Musedata (http://www.ccarh.org/musedata/) is an electronic library of
-classical music scores, currently comprising XXX scores. The music is
-encoded in so-called Musedata format
-(http://www.ccarh.org/publications/books/beyondmidi/online/musedata).
-musedata2ly converts a set of musedata files to one .ly file, and will
-include a \header field if a .ref file is supplied.
-
-This converter is not complete -- this is left to the user as an excercise.
-
-Report bugs to bug-lilypond@gnu.org.
-
-Written by Han-Wen Nienhuys <hanwen@cs.uu.nl>.
-
-""")
-
-
-def print_version ():
- sys.stdout.write ("""musedata2ly (GNU LilyPond) %s
-
-This is free software. It is covered by the GNU General Public License,
-and you are welcome to change it and/or distribute copies of it under
-certain conditions. Invoke as `midi2ly --warranty' for more information.
-
-Copyright (c) 2000--2004 by Han-Wen Nienhuys <hanwen@cs.uu.nl>.
-""" % version)
-def identify():
- sys.stderr.write ("%s from LilyPond %s\n" % (program_name, version))
-
-
-
-(options, files) = getopt.getopt (sys.argv[1:], 'r:vo:h', ['verbose', 'ref=', 'help','version', 'output='])
-out_filename = None
-ref_file = None
-for opt in options:
- o = opt[0]
- a = opt[1]
- if o== '--help' or o == '-h':
- help ()
- sys.exit (0)
- elif o == '--version' or o == '-v':
- print_version ()
- sys.exit(0)
- elif o == '--ref' or o == '-r':
- ref_file = a
- elif o == '--output' or o == '-o':
- out_filename = a
- elif o == '--verbose' :
- verbose = 1
- else:
- print o
- raise getopt.error
-
-identify()
-
-
-
-ly = ''
-
-
-found_ids = ''
-
-for f in files:
- if f == '-':
- f = ''
-
- sys.stderr.write ('Processing `%s\'\n' % f)
-
- e = Parser(f)
-
- id = os.path.basename (f)
- id = re.sub ('[^a-zA-Z0-9]', 'x', id)
-
- def num2let (match):
- return chr (ord (match.group ()) - ord('0') + ord('A'))
-
- id = re.sub ('[0-9]', num2let, id)
-
- id = 'voice%s' % id
- ly =ly + '\n\n%s = \\context Staff = "%s" %s\n\n' % (id, id, e.dump ())
-
- found_ids = found_ids + '\\%s\n' % id
-
-found_ids = '\n\n\n\\score { << %s >> } ' % found_ids
-
-ly_head = ''
-if ref_file:
- head = Ref_parser (ref_file)
- if not out_filename:
- t = ''
- st = ''
- try:
- t = head.dict['title']
- st= head.dict['subtitle']
- except KeyError:
- pass
-
- t = t + '-' +st
-
- t = re.sub ("^ +(.*) +$", r"\1", t)
- t = re.sub ("\\.", '', t)
- out_filename = re.sub ('[^a-zA-Z0-9-]', '-', t)
- out_filename = out_filename+ '.ly'
- ly_head = head.dump ()
-
-if not out_filename:
- out_filename = 'musedata.ly'
-
-sys.stderr.write ('Writing `%s\'\n' % out_filename)
-
-fo = open (out_filename, 'w')
-fo.write ('%% lily was here -- automatically converted by musedata.ly\n')
-fo.write(ly_head + ly + found_ids)
-fo.close ()
-
projects / lilypond.git / commitdiff