+2003-04-24 <hanwen@cs.uu.nl>
+
+ * Documentation/user/invoking.itexi (Invoking LilyPond): revise
+
+ * Documentation/user/converters.itely (Invoking convert-ly): revise
+
+ * scripts/convert-ly.py (outfile_name): remove --assume-old.
+
+ * scripts/lilypond-book.py (schedule_lilypond_block): remove --read-lys
+
2003-04-24 Han-Wen Nienhuys <hanwen@cs.uu.nl>
* Documentation/user/internals.itely: more updates.
@node Converting from other formats
@chapter Converting from other formats
+Music can be entered also by importing it from other formats. This
+chapter documents the tools included in the distribution to do so.
+There are other tools that produce LilyPond input, for example GUI
+sequencers and XML converters. Refer to the
+@uref{website,http://lilypond.org} for more details.
+
+
+
@menu
* Invoking convert-ly:: Older LilyPond versions.
* Invoking midi2ly:: Importing MIDI.
The following options can be given:
@table @code
-@item -a,--assume-old
- If version number cannot be determined, apply all conversions.
@item -e,--edit
Do an inline edit of the input file. Overrides @code{--output}.
@item -f,--from=@var{from-patchlevel}
@refbugs
-Not all language changes are handled. Only one output options can be specified.
+Not all language changes are handled. Only one output option can be specified.
@node Invoking midi2ly
@section Invoking midi2ly
This script was updated last in September 2000, and then successfully
converted the @file{barsant.pmx} example from the PMX
-distribution. Apparently no-one has ever bothered to use pmx2ly, since
-pmx2ly can not parse recent PMX files.
+distribution. pmx2ly cannot parse more recent PMX files.
@node Invoking musedata2ly
@section Invoking mup2ly
MUP (Music Publisher) is a shareware music notation program by Arkkra
-Enterprises. It is also the name of the input format. Mup2ly will
-convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is
-invoked as follows:
+Enterprises. Mup2ly will convert part of a Mup file to LilyPond
+format. It is invoked as follows:
@cindex Music Publisher
@cindex MUP
@table @code
@item -d,--debug
show what constructs are not converted, but skipped.
-@item D, --define=@var{name}[=@code{exp}]
+@item -D, --define=@var{name}[=@code{exp}]
define macro @var{name} with opt expansion @code{exp}
@item -E,--pre-process
only run the pre-processor
@end example
-When invoked with a filename that has no extension, LilyPond will try
-to add @file{.ly} as an extension first. To have LilyPond read from
-stdin, use a dash @code{-} for @var{file}.
+When invoked with a filename that has no extension, the @file{.ly}
+extension is tried first. To read input from stdin, use a
+dash @code{-} for @var{file}.
-When LilyPond processes @file{filename.ly} it will produce
+When @file{filename.ly} is processed it will produce
@file{filename.tex} as output (or @file{filename.ps} for PostScript
output). If @file{filename.ly} contains more than one @code{\score}
-block, then LilyPond will output the rest in numbered files, starting
-with @file{filename-1.tex}. Several files can be specified; they will
-each be processed independently. @footnote{The status of GUILE is not
-reset across invocations, so be careful not to change any default
-settings from within Scheme .}
+block, then the rest of the scores will be output in numbered files,
+starting with @file{filename-1.tex}. Several files can be specified;
+they will each be processed independently. @footnote{The status of
+ GUILE is not reset across invocations, so be careful not to change any
+ default settings from within Scheme .}
@section Command line options
@item GS_LIB
For processing PostScript output (obtained with
@code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
-point to the directory containing LilyPond PS files.
+point to the directory containing library PS files.
@item GS_FONTPATH
For processing PostScript output (obtained with
@code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
-point to the directory containing LilyPond PFA files.
+point to the directory containing PFA files.
When you print direct PS output, remember to send the PFA files to the
printer as well.
@cindex TEXMF
@cindex printing postscript
-The LilyPond binary itself recognizes the following environment variables
+The binary itself recognizes the following environment variables
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@item LANG
-This selects the language for the warning messages of LilyPond.
+This selects the language for the warning messages
@end table
@cindex LANG
Since there is no finder's fee which doubles every year, there is no
need to wait for the prize money to grow. Send a bug report today!
-LilyPond development moves quickly, so if you have a problem, it is
+Development moves quickly, so if you have a problem, it is
wise to check if it has been fixed in a newer release. If not, please
send in a bugreport. When you send us a bugreport, we have to
diagnose the problem and if necessary, duplicate it. To make this
@c move this elsewhere?
-LilyPond also comes with support files for emacs: lilypond-mode for
-emacs provides indentation, autocompletion, syntax coloring, handy
-compile short-cuts and reading Info documents of lilypond inside emacs.
-If lilypond-mode is not installed on your platform,
-then refer to the installation instructions for more information.
+There is also support for emacs: lilypond-mode for emacs provides
+indentation, autocompletion, syntax coloring, handy compile short-cuts
+and reading Info documents of lilypond inside emacs. If lilypond-mode
+is not installed on your platform, then refer to the installation
+instructions for more information.
@cindex emacs
@cindex emacs mode
@subsection Additional parameters
Ly2dvi responds to several parameters specified in a @code{\paper}
-section of the LilyPond file. They can be overridden by supplying a
+section of the input file. They can be overridden by supplying a
@code{--set} command line option.
@table @code
@subsection Environment variables
@table @code
-@item LANG
-selects the language for the warning messages of Ly2dvi and LilyPond.
-
-@item GUILE_MAX_SEGMENT_SIZE
-is an option for GUILE, the scheme interpreter; it sets the size of
-the chunks of memory allocated by GUILE. By increasing this from its
-default 8388608, the performance of LilyPond on large scores is
-slightly improved.
@end table
@end ignore
-@node Integrating text and music with lilypond-book
-@chapter Integrating text and music with lilypond-book
+@node lilypond-book manual
+@chapter lilypond-book manual
If you want to add pictures of music to a document, you can simply do
it the way you would do with other types of pictures. You write
font size definitions for the music are adjusted to match the layout
of your document.
-It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
-on using lilypond-book is in @ref{Integrating text and music}. In
-case that you do not know La@TeX{}, then
+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}. In case that you do not know La@TeX{}, then
@uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
Short Introduction to LaTeX} provides a introction to using La@TeX{}.
@code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
environment from the multicol package.
-The music will be surrounded by @code{\preLilypondExample} and
-@code{\postLilypondExample}. The variables are
-defined to nothing by default, and the user can redefine them
-to whatever he wants.
+If you want to add titling from the @code{\header} section of the
+files, you should add the following to the top of your La@TeX{} file:
+
+@example
+\input titledefs.tex
+\def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
+@end example
+
+The music will be surrounded by @code{\preLilypondExample} and
+@code{\postLilypondExample}, which are defined to be empty by default.
@node Integrating HTML and music
@section Integrating HTML and music
@node Music fragment options
@section Music fragment options
-The commands for lilypond-book have room to specify options. These
-are all of the options:
+The commands for lilypond-book have room to specify one or more of the
+following options:
@table @code
@item eps
document with the @code{\includegraphics} command. It works in
La@TeX{} only.
+
This enables you to place music examples in the running text (and not in
a separate paragraph). To avoid that La@TeX{} places the music on a line
of its own, there should be no empty lines between the normal text and
}
@end lilypond
-@item singleline
-Produce a single, naturally spaced, unjustified line
-(i.e., @code{raggedright = ##t}).
+@item raggedright
+Produce naturally spaced lines (i.e., @code{raggedright = ##t}); this
+works well for small music fragments.
@item multiline
The opposite of @code{singleline}: Justify and break lines.
affects LilyPond, not the text layout.
@item notexidoc
-Do not include the .texidoc header. This is only for Texinfo output.
+Do not include @code{texidoc}. This is only for Texinfo output.
+
+In Texinfo, the music fragment is normally preceded by the
+@code{texidoc} field from the @code{\header}. The LilyPond test
+documents are composed from small @file{.ly} files in this way,
+
+@example
+ \header @{
+ texidoc = "this file demonstrates a single note"
+ @}
+ \score @{ \notes { c'4 @} @}
+@end example
@item quote
-Instruct @command{lilypond-book} to put La@TeX{} and texinfo output
+Instruct @command{lilypond-book} to put La@TeX{} and Texinfo output
into a quotation block.
@item printfilename
@item relative, relative @var{N}
Use relative octave mode. By default, notes are specified relative
-central C. The optional integer argument specifies how many octaves
-higher (positive number) or lower (negative number) to place the
-starting note.
+central C. The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is central C.
@end table
out automatically.
The @code{texi} document type produces a DVI file; to convert a
-texinfo document to @code{html}, you should use the additional format
+Texinfo document to @code{html}, you should use the additional format
@code{texi-html} instead of @code{texi} to convert lilypond fragments
to PNG images.
@item @option{--no-pictures}
Do not generate pictures when processing Texinfo.
-@item @option{--read-lys}
-Do not write ly files. This way you can do
-
-@example
-lilypond-book file.tely
-convert-ly
-lilypond-book --read-lys
-@end example
-
@item @option{--outname=@var{file}}
The name of La@TeX{} file to output. If this option is not given,
the output name is derived from the input name.
The La@TeX{} @code{\includeonly@{...@}} command is ignored.
-The Texinfo command @code{pagesize} is on the TODO list for LilyPond
-1.8, but changing the linewidth in other ways will not give you a
-straight right margin.
+The Texinfo command @code{pagesize} is not interpreted. Almost all
+La@TeX{} commands that change margins and line widths are ignored.
-Almost all La@TeX{} commands that change margins and line widths are
-ignored.
+The size of a lilypond block is limited to 1.5 kb, due to technical
+problems with Python's regular expressions. For longer files, use
+@code{\lilypondfile}. Using @code{\lilypondfile} also makes upgrading
+files (through convert-ly, see @ref{Invoking convert-ly}) easier.
-There is no way to automatically apply @command{convert-ly} only to fragments
-inside a lilypond-book file.
-@command{lilypond-book} processes all music fragments in one big run. The
-state of the GUILE interpreter is not reset between fragments; this
-means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
-and @code{#(set! @dots{})} can leak from one fragment into the next fragment.
+@command{lilypond-book} processes all music fragments in one big run.
+The state of the GUILE interpreter is not reset between fragments;
+this means that changes made to global GUILE definitions, e.g., done
+with @code{set!} or @code{set-cdr!}, can leak from one fragment into
+the next fragment.
@mbinclude introduction.itely
@mbinclude tutorial.itely
@mbinclude refman.itely
+@mbinclude literature.itely
@mbinclude internals.itely
@mbinclude invoking.itexi
@mbinclude lilypond-book.itely
@mbinclude converters.itely
-@mbinclude literature.itely
@c FIXME: Index has two alphabetically sorted lists @code vs plain?
staff symbol.
This object is created whenever a @internalsref{Staff} context is
-created. You can not change the appearance of the staff symbol by
+created. You cannot change the appearance of the staff symbol by
using @code{\override} or @code{\set}. At the moment that
@code{\property Staff} is interpreted, a Staff context is made, and
the @internalsref{StaffSymbol} is created before any @code{\override} is
@refbugs
Resolving collisions is a very intricate subject, and LilyPond only
-handles a few situations. When it can not cope, you are advised to use
+handles a few situations. When it cannot cope, you are advised to use
@code{force-hshift} of the @internalsref{NoteColumn} object and pitched
rests to override typesetting decisions.
@cindex hara kiri
-Automatically kneed beams can not be used together with Hara Kiri
+Automatically kneed beams cannot be used together with Hara Kiri
staves.
@refbugs
-Grace notes can not be used in the smallest size (@file{paper11.ly}).
+Grace notes cannot be used in the smallest size (@file{paper11.ly}).
Grace note synchronization can also lead to surprises. Staff notation,
such as key signatures, barlines, etc. are also synchronized. Take
@refbugs
-You can not nest percent repeats, e.g. by filling in the first measure
+You cannot nest percent repeats, e.g. by filling in the first measure
with slashes, and repeating that measure with percents.
@node Rhythmic music
@end lilypond
In chord mode, dashes and carets are used to indicate chord additions
-and subtractions, so articulation scripts can not be entered.
+and subtractions, so articulation scripts cannot be entered.
@node Printing chord names
Relative size is not linked to any real size.
There is no style sheet provided for other fonts besides the @TeX{}
-family, and the style sheet can not be modified easily.
+family, and the style sheet cannot be modified easily.
@cindex font selection
@cindex font magnification
transposition has no effect, as central C stays at central C.
The purpose of this no-op is to protect it from being interpreted as
-relative notes. Relative mode can not be used together with
+relative notes. Relative mode cannot be used together with
transposition, so @code{\relative} will leave the contents of
@code{\hoomPah} alone. We can use it without having to worry about
getting the motive in a wrong octave. Conversely, if you want to
input is guessed by default from \version directive
Options:
- -a, --assume-old apply all conversions to unversioned files
-h, --help print this help
-e, --edit in place edit
-f, --from=VERSION start from version. Overrides \version found in file.
outfile_name = ''
(options, files) = getopt.getopt (
- sys.argv[1:], 'ao:f:t:senh', ['no-version', 'assume-old', 'version', 'output', 'show-rules', 'help', 'edit', 'from=', 'to='])
+ sys.argv[1:], 'ao:f:t:senh', ['no-version', 'version', 'output', 'show-rules', 'help', 'edit', 'from=', 'to='])
for opt in options:
o = opt[0]
sys.exit(0)
elif o == '--output' or o == '-o':
outfile_name = a
- elif o == '--assume-old' or o == '-a':
- assume_old = 1
elif o == '--no-version' or o == '-n':
add_version = 0
else:
('', 'n', 'no-lily', _ ("don't run lilypond")),
('', '', 'no-pictures', _ ("don't generate pictures")),
('', '', 'no-music', _ ("strip all lilypond blocks from output")),
- ('', '', 'read-lys', _ ("don't write ly files.")),
(_ ("FILE"), 'o', 'outname', _ ("filename main output file")),
(_ ("FILE"), '', 'outdir', _ ("where to place generated files")),
(_ ('RES'), '', 'preview-resolution',
g_dep_prefix = ''
g_outdir = ''
g_force_music_fontsize = 0
-g_read_lys = 0
g_do_pictures = 1
g_do_music = 1
g_make_html = 0
else:
taken_file_names[basename] = taken_file_names[basename] + 1
basename = basename + "-%i" % taken_file_names[basename]
- if not g_read_lys:
- update_file (file_body, os.path.join (g_outdir, basename) + '.ly')
+ update_file (file_body, os.path.join (g_outdir, basename) + '.ly')
needed_filetypes = ['tex']
if format == 'html' or g_make_html:
g_do_pictures = 0
elif o == '--no-music':
g_do_music = 0
- elif o == '--read-lys':
- g_read_lys = 1
elif o == '--outdir':
g_outdir = a
elif o == '--warranty' or o == '-w':