[lilypond.git] / Documentation / programs.texi

\input texinfo @c -*-texinfo-*-
@setfilename programs.info
@settitle Programs

@node Top, , midi2ly Authors, (dir)
@top
@menu
* Programs::                      Your Softs-
* convert-mudela::                convert-mudela to newer versions
* LilyPond::                      the GNU Music Typesetter
* Ly2dvi::                        Python utility to convert mudela to DVI
* midi2ly::                       convert MIDI to -mudela-
@end menu




@node Programs, convert-mudela, , Top
@chapter Programs








@node convert-mudela, convert-mudela DESCRIPTION, Programs, Top
@menu
* convert-mudela DESCRIPTION::    convert-mudela DESCRIPTION
* convert-mudela SYNOPSIS::       convert-mudela SYNOPSIS
* convert-mudela OPTIONS::        convert-mudela OPTIONS
* convert-mudela BUGS::           convert-mudela BUGS
* convert-mudela Authors::        convert-mudela Authors
@end menu
@chapter convert-mudela

convert-mudela sequentially applies different mudela-conversions to
upgrade a Mudela input file.

@node convert-mudela DESCRIPTION, convert-mudela SYNOPSIS, convert-mudela, convert-mudela
@section DESCRIPTION

Upgrade a Mudela input file from FROM_PATCHLEVEL to TO_PATCHLEVEL.
If no files are given, the standard input and output are used.

@node convert-mudela SYNOPSIS, convert-mudela OPTIONS, convert-mudela DESCRIPTION, convert-mudela
@section SYNOPSIS

        convert-mudela [options] [files]

@node convert-mudela OPTIONS, convert-mudela BUGS, convert-mudela SYNOPSIS, convert-mudela
@section OPTIONS
@table @samp
@item --output
    The output file to write.  
@item --edit
    Do an inline edit of the input file. override @code{--output}
@item --show-rules
    shows all known conversions, and exit
@item --from=FROM_PATCHLEVEL
    Set the level to convert from. If this is not set, convert-mudela will
    guess this, on the basis of @code{\version} strings in the file
@item --to=TO_PATCHLEVEL
    Set the goal version of the conversion. It defaults to the latest
    available version.
@end table

@node convert-mudela BUGS, convert-mudela Authors, convert-mudela OPTIONS, convert-mudela
@section BUGS

Not all language changes are handled. Multiple output options won't
work.

convert-mudela is written in python, so you have install
@uref{http://www.python.org,python}.

@node convert-mudela Authors, LilyPond, convert-mudela BUGS, convert-mudela
@section Authors

@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen}








@node LilyPond, LilyPond SYNOPSIS, convert-mudela Authors, Top
@menu
* LilyPond SYNOPSIS::             LilyPond SYNOPSIS
* LilyPond DESCRIPTION::          LilyPond DESCRIPTION
* LilyPond OPTIONS::              LilyPond OPTIONS
* LilyPond FEATURES::             LilyPond FEATURES
* LilyPond DISCLAIMER::           LilyPond DISCLAIMER
* LilyPond PROBLEMS::             LilyPond PROBLEMS
* LilyPond FILES::                LilyPond FILES
* LilyPond environment::          LilyPond environment
* LilyPond BUGS::                 LilyPond BUGS
* LilyPond SEE ALSO::             LilyPond SEE ALSO
* LilyPond REMARKS::              LilyPond REMARKS
* LilyPond Authors::              LilyPond Authors
@end menu
@chapter LilyPond

@cindex LilyPond

@node LilyPond SYNOPSIS, LilyPond DESCRIPTION, LilyPond, LilyPond
@section SYNOPSIS
        @strong{lilypond} [OPTION]... [MUDELA-FILE]...

@node LilyPond DESCRIPTION, LilyPond OPTIONS, LilyPond SYNOPSIS, LilyPond
@section DESCRIPTION

LilyPond is a music typesetter.  It produces beautiful sheet music
using a high level description file as input.  LilyPond is part of 
the GNU Project.


@node LilyPond OPTIONS, LilyPond FEATURES, LilyPond DESCRIPTION, LilyPond
@section OPTIONS
@table @samp
@item -f,--format=
        Output format for sheet music. Choices are tex (for TeX
        output), ps (for PostScript) and scm (for GUILE)
@item -I,--include=
    add @file{FILE} to the search path for input files.
@item -m,--midi
    Disable TeX output. If you have a \midi definition, it will do the 
    midi output only.
@item -M,--dependencies
    Also output rules to be included in Makefile.
@item -d,--debug
    Turn debugging info on.  GNU LilyPond reads the file @file{.dstreamrc}, 
    which lists what functions and classes may produce copious debugging
    output.
@item -s,--safe
    Disallow untrusted @code{\include} directives, backslashes in TeX
code and named output.
@item -t,--test
    Switch on any experimental features.  Not for general public use.
@item -w,--warranty
    Show the warranty with which GNU LilyPond comes. (It comes with 
    @strong{NO WARRANTY}!)
@item -o,--output=FILE
    Set the default output file to @file{FILE}.
@item -h,--help
    Show a summary of usage.
@item -i,--init=FILE
    Set init file to @file{FILE} (default: @file{init.ly}).
@item --include, -I=DIRECTORY
    Add @file{DIRECTORY} to the search path for input files.
@item --ignore-version, -V
    Make the incompatible mudela version warning non-fatal.
@end table

@node LilyPond FEATURES, LilyPond DISCLAIMER, LilyPond OPTIONS, LilyPond
@section FEATURES

This is an overview of the features that GNU LilyPond supports.  For
details on how to use them, you should consult the Mudela tutorial,
which is included with the package.

@itemize @bullet
@item ASCII script input, with identifiers (for music reuse),
    customizable notenames, customisable fontset.
@item MIDI output lets you check if you have entered the correct notes.
@item MIDI to Mudela conversion through the mi2mu program.
@item Multiple staffs in one score.  Each staff can have different time signatures.
@item Beams, slurs, ties, chords, super/subscripts (accents and text)
    triplets, general n-plet (triplet, quadruplets, etc.), lyrics,
    transposition, dynamics (both absolute and hairpin style).
@item Multiple voices within one staff; beams optionally shared
    between voices.  Up to four voices is handled cleanly.
@item Multiple scores within one input file.  Each score is output to
    a different file.
@item Clef changes, meter changes, cadenza-mode, key changes, repeat bars.
@end itemize

@node LilyPond DISCLAIMER, LilyPond PROBLEMS, LilyPond FEATURES, LilyPond
@section DISCLAIMER

GNU LilyPond is copyright 1996-1999 by its authors.  GNU LilyPond is
distributed under the terms of the GNU General Public License.  GNU LilyPond 
is provided without any warranty what so ever.
GNU LilyPond may be freely distributed.  For further information consult 
the GNU General Public License, from the file @file{COPYING}.

@node LilyPond PROBLEMS, LilyPond FILES, LilyPond DISCLAIMER, LilyPond
@section PROBLEMS

There is an extensive list of todoes and bugs.  See the file
@file{TODO} distributed with the sources.  If you have a problem you
should try to find out

@itemize @bullet
@item If the bug has been fixed in a newer release.
@item If the bug has been found earlier, consult @file{TODO} and @file{BUGS}.
@end itemize

If you have found a bug, then we would appreciate it if you sent a
bugreport.

@itemize @bullet
@item Send a copy of the input which causes the error.
@item Send a description of the platform you use.
@item Send a description of the LilyPond version you use 
    (with compile/configure options please).
@item Send a description of the bug itself.
@item Send it to @email{bug-gnu-music@@gnu.org}; you don't have to be subscribed
    to this mailinglist.
@end itemize

@node LilyPond FILES, LilyPond environment, LilyPond PROBLEMS, LilyPond
@section FILES
@table @samp
@item @file{init.ly} 
    The initialisation file with symbol tables etc.  It
    includes files from the directory
    @file{PREFIX/share/lilypond/ly/}. (@file{PREFIX} typically is @file{/usr/local}
)@end table

@node LilyPond environment, LilyPond BUGS, LilyPond FILES, LilyPond
@section environment

@table @samp
@item LILYINCLUDE
    additional directories for finding lilypond data.  The
    format is like the format of @file{PATH}.
@item LILYPREFIX
        [FIXME]
@item LANG
    selects the language for the warning messages of LilyPond.
@end table

@node LilyPond BUGS, LilyPond SEE ALSO, LilyPond environment, LilyPond
@section BUGS

Lots of them.  See @file{TODO} and @file{BUGS}

@node LilyPond SEE ALSO, LilyPond REMARKS, LilyPond BUGS, LilyPond
@section SEE ALSO

LilyPond comes with various other documentation files.  They are
included in the source package.

A further source for information is the website, which can be found at
@uref{http://www.lilypond.org/}.  The website contains on-line versions
of the documentation

GNU LilyPond is updated very frequently, the latest version is always
available at: @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond}.  This FTP
site is mirrored at a number of sites; consult the project web pages
for information about mirrors.

For programs which are part of the GNU music project, the following
mailing list have been setup:

@table @samp
@item @email{info-gnu-music@@gnu.org} 
    For information on the GNU Music project, to subscribe: send mail with
    subject "subscribe" to @email{info-gnu-music-request@@gnu.org}
@item @email{help-gnu-music@@gnu.org} 
    For help with programs from the GNU music project.  To subscribe: send
    mail with subject "subscribe" to @email{help-gnu-music-request@@gnu.org}
@item @email{bug-gnu-music@@gnu.org}
    If you have bugreports, you should send them to this list.  If you want
    to read all bugreports, you should subscribe to this list.  To
    subscribe: send mail with subject "subscribe" to
    @email{bug-gnu-music-request@@gnu.org}
@item @email{gnu-music-discuss@@gnu.org}
    For discussions concerning the GNU Music project, to subscribe: send
    mail with subject "subscribe" to
    @email{gnu-music-discuss-request@@gnu.org}
@end table

Announces of new versions will be sent to info-gnu-music and
gnu-music-discuss.

@node LilyPond REMARKS, LilyPond Authors, LilyPond SEE ALSO, LilyPond
@section REMARKS

GNU LilyPond has no connection with the music package Rosegarden, other
than the names being similar :-)

@node LilyPond Authors, Ly2dvi, LilyPond REMARKS, LilyPond
@section Authors

@cindex Author

@itemize @bullet
@item @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}
    @uref{http://www.cs.uu.nl/people/hanwen}
@item @email{janneke@@gnu.org, Jan Nieuwenhuizen}
    @uref{http://www.xs4all.nl/~jantien}
@end itemize

Please consult the documentation file @file{AUTHORS} for more detailed
information, and small contributions.




@node Ly2dvi, Ly2dvi DESCRIPTION, LilyPond Authors, Top
@menu
* Ly2dvi DESCRIPTION::            Ly2dvi DESCRIPTION
* Ly2dvi SYNOPSIS::               Ly2dvi SYNOPSIS
* Ly2dvi OPTIONS::                Ly2dvi OPTIONS
* Ly2dvi Features::               Ly2dvi Features
* Ly2dvi Environment::            Ly2dvi Environment
* Ly2dvi Files::                  Ly2dvi Files
* Ly2dvi Initialization Sequence::Ly2dvi Initialization Sequence
* Ly2dvi See Also::               Ly2dvi See Also
* Ly2dvi Bugs::                   Ly2dvi Bugs
* Ly2dvi Remarks::                Ly2dvi Remarks
* Ly2dvi Authors::                Ly2dvi Authors
@end menu
@chapter Ly2dvi

@node Ly2dvi DESCRIPTION, Ly2dvi SYNOPSIS, Ly2dvi, Ly2dvi
@section DESCRIPTION
ly2dvi is a Python script which creates input file for LaTeX,
based on information from the output files from LilyPond.
The script handles multiple files. If a mudela file name is
specified LilyPond is run to make an output (TeX) file.

One or more LaTeX files are created, based on information found
in the output (TeX) files, and latex is finally run to create
one or more DVI files.

The majority of this utility came from a bourne script written by Jan
Arne Fagertun name @file{ly2dvi}. 

@node Ly2dvi SYNOPSIS, Ly2dvi OPTIONS, Ly2dvi DESCRIPTION, Ly2dvi
@section SYNOPSIS

        ly2dvi [options] inputfile[.ly] [....]

@node Ly2dvi OPTIONS, Ly2dvi Features, Ly2dvi SYNOPSIS, Ly2dvi
@section OPTIONS

@table @samp
@item -D,--debug
    Set debug mode. There are two levels - in level one some debug
    info is written, in level two the command @strong{set -x} is run, which
    echoes every command in the ly2dvi script.
@item -F,--headers=
    Name of additional LaTeX headers file. This is included in the
    tex file at the end of the headers, last line before @code{\begin@{document@}}
@item -H,--Heigth=
    Set paper heigth (points). Used together with width and LaTeX name of
    papersize in case of papersize unknown to ly2dvi.
@item -K,--keeplilypond
    Keep LilyPond output after the run.
@item -L,--landscape
    Set landscape orientation - portrait is the default.
    (@strong{-L} produces @code{\usepackage[landscape]@{article@}})
@item -N,--nonumber
    Switch off page numbering.
@item -O,--orientation=
    Set orientation landscape - obsolete, use @strong{-L} instead.
@item -P,--postscript
    In addition to the DVI file, also Generate a postsript file.
@item -W,--Width=
    Set paper width (points). Used together with heigth and LaTeX name of
    papersize in case of papersize unknown to ly2dvi.
@item -d,--dependencies
    Tell lilypond to make dependencies file.
@item -h,--help
    Print help.
@item -k,--keeply2dvi
    Keep the LaTeX file after the run.
@item -l,--language=
    Specify LaTeX language.
    (@strong{-l norsk} produces @code{\usepackage[norsk]@{babel@}}).
@item -o,--output=
    Set output directory.
@item -p,--papersize=
    Specify papersize.
    (@strong{-p a4} produces @code{\usepackage[a4paper]@{article@}})
@item -s,--separate
    Normally all output files are included into one LaTeX file.
    With this switch all files are run separately, to produce one
    DVI file for each.
@end table

@node Ly2dvi Features, Ly2dvi Environment, Ly2dvi OPTIONS, Ly2dvi
@section Features

ly2dvi responds to several parameters specified in the mudela
file. They are overridden by corresponding command line options.

@table @samp
@item language="";
    Specify LaTeX language
@item latexheaders="";
    Specify additional LaTeX headers file
@item orientation="";
    Set orientation.
@item paperlinewidth="";
    Specify the width (pt, mm or cm) of the printed lines.
@item papersize="";
    Specify name of papersize.
@end table

@node Ly2dvi Environment, Ly2dvi Files, Ly2dvi Features, Ly2dvi
@section Environment

@table @samp
@item LILYPONDPREFIX
    Sets the root directory of the LilyPond installation
@item LILYINCLUDE
    Additional directories for input files.
@item TMP
    Temporary directory name. Default is /tmp
@end table

@node Ly2dvi Files, Ly2dvi Initialization Sequence, Ly2dvi Environment, Ly2dvi
@section Files

@file{titledefs.tex} is inspected for definitions used to extract
additional text definitions from the mudela file. In the current
version the following are defined:

@table @samp
@item title
    The title of the music. Centered on top of the first page.
@item subtitle
    Subtitle, centered below the title.
@item poet
    Name of the poet, leftflushed below the below subtitle.
@item composer
    Name of the composer, rightflushed below the subtitle.
@item metre
    Meter string, leftflushed below the below poet.
@item opus
    Name of the opus, rightflushed below the below composer.
@item arranger
    Name of the arranger, rightflushed below the opus.
@item instrument
    Name of the instrument, centered below the arranger
@item piece
    Name of the piece, leftflushed below the instrument
@end table

@file{$LILYPONDPREFIX/share/.lilyrc $HOME/.lilyrc ./.lilyrc} are files
to set up default running conditions.  On Windows OS initialization
files are named @file{_lilyrc}. The file syntax is as follows:

@example 
VARIABLE-NAME=VALUE 
@end example 
 

Where @strong{VARIABLE-NAME} is the name of the variable documented below
and @strong{VALUE} is either a string, a 1, or a 0.  All files are parsed,
in the shown sequence. In the current version the following are
allowed:

@table @samp
@item DEBUG=value
This turns off (default) or on the debug capabilities.  Possible
values are 0 (off) and 1 (on).
@item DEPENDENCIES=value
This turns off (default) or on the ability to generate a Makefile
dependency list.  Possible values are 0 (off) and 1 (on).
@item KEEPLILYPOND=value
This turns off (default) or on the ability to keep the log file
associated with the LilyPond job.  Possible values are 0 (off) and 1
(on).
@item KEEPLY2DVI=value
This turns off (default) or on the ability to keep the temporary files
that are generated by the ly2dvi job.  Possible values are 0 (off) and
1 (on)
@item LANGUAGE=value
Specify LaTeX language.  Possible value is a valid LaTeX language.
@item LATEXHF=value
Specify additional LaTeX headers file.  Possible value is a file
specification. 
@item LILYINCLUDE=value
Additional directories for input files.  Possible value is a delimited
directory path list.
@item LILYPONDPREFIX=value
This defines the LilyPond root directory.  Possible value is a valid
directory specification to the LilyPond distribution location.
@item NONUMBER=value
This turns off (default) or on the page numbering capability.
Possible values are 0 (page numbering enabled) and 1 (page numbering
disabled). 
@item ORIENTATION=value
This sets the image orientation.  Possible values are
portrait (default) and landscape.
@item OUTPUTDIR=value
This defines the directory where the resultant files will be
generated.  Possible value is a valid directory specification.
Default is the current working directory.
@item PAPERSIZE=value
This defines the papersize the image will be sized to fit.  Possible
values are a0, a1, a2, a3, a4 (default), a5, a6, a7, a8, a9, a10, b0,
b1, b2, b3, b4, b5, archA, archB, archC, archD, archE, flsa, flse,
halfletter, ledger, legal, letter, or note.
@item PHEIGHT=value
Specify paperheight (points - an inch is 72.27, a cm is 28.453 points).
@item POSTSCRIPT=value
This turns off (default) or on the capability of additionally
generating a postscript file.  Possible values are 0 (off) and 1 (on).
@item PWIDTH=value
Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points).
@item SEPARATE=value
This turns off (default) or on the capability of generating multiple
dvi and postscript files from multiple source files.  The default is
to generate a concatenation of the source files.  Possible values are
0 (single file) and 1 (separate files).
@item TMP=value
This defines the emporary directory.  Actually this is not used at the
present.  Possible value is a valid directory specification that is
writable to the user.
@end table

@node Ly2dvi Initialization Sequence, Ly2dvi See Also, Ly2dvi Files, Ly2dvi
@section Initialization Sequence
The initialization process reads inputs for several sources.  Below is
a list of priorities for lowest to hightest proirity.

@itemize @bullet
@item  Program's defaults
@item  Values found in LilyPond output file
@item  Environment variables
@item  $LILYPONDPREFIX/share/lilypond/.lilyrc
@item  $HOME/.lilyrc
@item  ./.lilyrc
@item  command line options
@end itemize

Note that this differs slightly from the original bourne shell
version. 

@node Ly2dvi See Also, Ly2dvi Bugs, Ly2dvi Initialization Sequence, Ly2dvi
@section See Also

lilypond(1), tex(1), latex(1)

@node Ly2dvi Bugs, Ly2dvi Remarks, Ly2dvi See Also, Ly2dvi
@section Bugs

If you have found a bug, you should send a bugreport.

@itemize @bullet
@item Send a copy of the input which causes the error.
@item Send a description of the platform you use.
@item Send a description of the LilyPond and ly2dvi version you use.
@item Send a description of the bug itself.
@item Send it to @email{bug-gnu-music@@gnu.org} (you don't have to subscribe
    to this mailinglist).
@end itemize

@node Ly2dvi Remarks, Ly2dvi Authors, Ly2dvi Bugs, Ly2dvi
@section Remarks

Many papersizes are now supported. Information on other sizes
(LaTeX names, horizontal and vertical sizes) should be mailed to
the author or to the mailing list.

Supported papersizes are:

a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD,
archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal,
letter, note

@node Ly2dvi Authors, midi2ly, Ly2dvi Remarks, Ly2dvi
@section Authors
Python Version author:
@email{daboys@@austin.rr.com, Jeffrey B. Reed},
@uref{http://home.austin.rr.com/jbr/jeff/lilypond/}

Original bourne shell version author:
@email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun},
@uref{http://www.termo.unit.no/mtf/people/janaf/}







@node midi2ly, midi2ly DESCRIPTION, Ly2dvi Authors, Top
@menu
* midi2ly DESCRIPTION::           midi2ly DESCRIPTION
* midi2ly OPTIONS::               midi2ly OPTIONS
* midi2ly DISCLAIMER::            midi2ly DISCLAIMER
* midi2ly SEE ALSO::              midi2ly SEE ALSO
* midi2ly Authors::               midi2ly Authors
@end menu
@chapter midi2ly

@node midi2ly DESCRIPTION, midi2ly OPTIONS, midi2ly, midi2ly
@section DESCRIPTION
midi2ly translates a MIDI input file to Mudela (GNU LilyPond source
format).  midi2ly is part of the GNU LilyPond music typesetting package.

        midi2ly [options] midi-file

@node midi2ly OPTIONS, midi2ly DISCLAIMER, midi2ly DESCRIPTION, midi2ly
@section OPTIONS

@table @samp
@item -b, --no-quantify,
    Write exact durations, e.g.: `a4*385/384'.
@item -D, --debug,
    Print lots of debugging stuff.
@item -h, --help,
    Show a summary of usage.
@item -I, --include=@file{DIR},
    Add DIR to search path.
@item -k, --key=ACC[:MINOR],
    Set default key.  ACC > 0 sets number of sharps; ACC < 0 sets number 
    of flats.  A minor key is indicated by ":1".
@item -n, --no-silly,
    Assume no plets or double dots, assume smallest (reciprocal) duration 16.
@item -o, --output=@file{FILE},
    Set @file{FILE} as default output.
@item -p, --no-plets,
    Assume no plets.
@item -q, --quiet,
    Be quiet.
@item -s, --smallest=N,
    Assume no shorter (reciprocal) durations than N.
@item -v, --verbose,
    Be verbose.
@item -w, --warranty,
    Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
@item -x, --no-double-dots,
    Assume no double dotted notes.
@end table

@node midi2ly DISCLAIMER, midi2ly SEE ALSO, midi2ly OPTIONS, midi2ly
@section DISCLAIMER

midi2ly is copyright 1996, 1997 by its authors. midi2ly is distributed 
as part of GNU LilyPond, under the terms of the GNU General Public
License.  midi2ly is provided without any warranty what so ever.
midi2ly may be freely distributed.  For further information consult
the GNU General Public License, from the file @file{COPYING}.

@node midi2ly SEE ALSO, midi2ly Authors, midi2ly DISCLAIMER, midi2ly
@section SEE ALSO

@table @samp
@item @strong{lilypond}(1)
    The GNU LilyPond music typesetter.
@end table

@node midi2ly Authors, Top, midi2ly SEE ALSO, midi2ly
@section Authors

Please consult the documentation file @file{AUTHORS} for more detailed
information, and small contributions. 

@email{janneke@@gnu.org, Jan Nieuwenhuizen}, @uref{http://www.xs4all.nl/~jantien}





@bye