version that you are working on. See TRANSLATION for details.
@end ignore
-@c was "INSTALL - compiling and installing GNU LilyPond"
+@c \version "2.12.0"
+
@node Setup
@chapter Setup
-This chapter discusses how to set up LilyPond to integrate with various
-programs.
+This chapter discusses various post-install configuration options for
+LilyPond and various other programs. This chapter may be safely treated
+as a reference: only read a section if it applies to you.
+
+@menu
+* Setup for specific Operating Systems::
+* Text editor support::
+* Point and click::
+@end menu
+
+
+@node Setup for specific Operating Systems
+@section Setup for specific Operating Systems
+
+This section explains how to perform additional setup for specific
+operating systems.
@menu
-* Notes for the MacOS X app::
-* Text editor support::
+* Setup for MacOS X::
@end menu
+@node Setup for MacOS X
+@subsection Setup for MacOS X
+
+@subsubheading Using Python scripts on MacOS 10.3 or 10.4
+
+LilyPond binaries for MacOS X do not provide Python, but Python 2.4 or
+newer is required by @command{convert-ly}. Therefore, if you use MacOS
+10.3 or 10.4, you must install a newer Python version from
+@uref{http://python.org/download/}, then edit the first line of
+@command{convert-ly} and @command{lilypond-book} as follows: if the
+Python binary you just installed is in your @var{PATH}, the first line
+should be
+
+@example
+#!/usr/bin/env python
+@end example
+
+@noindent
+otherwise it should be
+
+@example
+#!@var{/path/to/newly_installed/python}
+@end example
+
-@node Notes for the MacOS X app
-@section Notes for the MacOS X app
+@subsubheading MacOS X on the command line
-The scripts (such as lilypond-book, convert-ly, abc2ly, and even
-lilypond itself) are also
-included inside MacOS X .app. They can be run from the command line by
-invoking them directly, e.g.
+The scripts --- such as @command{lilypond-book}, @command{convert-ly},
+@command{abc2ly}, and even @command{lilypond} itself --- are included
+inside the @code{.app} file for MacOS@tie{}X. They can be run from
+the command line by invoking them directly, e.g.
@example
@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond
@noindent
The same is true of the other scripts in that directory, including
-lilypond-book, convert-ly, abc2ly, etc.
+@command{lilypond-book}, @command{convert-ly}, @command{abc2ly}, etc.
Alternatively, you may create scripts which add the path
automatically. Create a directory to store these scripts,
@node Text editor support
@section Text editor support
+@cindex editors
+@cindex vim
+@cindex emacs
+@cindex modes, editor
+@cindex syntax coloring
+@cindex coloring, syntax
+
+There is support from different text editors for LilyPond.
+
@menu
-* Emacs mode::
-* Vim mode::
+* Emacs mode::
+* Vim mode::
+* jEdit::
+* TexShop::
+* TextMate::
+* LilyKDE::
@end menu
@node Emacs mode
@subsection Emacs mode
+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 @file{lilypond-mode} is not installed on your
+platform, see below.
+
An Emacs mode for entering music and running LilyPond is contained in
the source archive in the @file{elisp} directory. Do @command{make
install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
your @var{load-path} by appending the following line (as modified) to your
@file{~/.emacs}
+
@c any reason we do not advise: (push "~/site-lisp" load-path)
-@quotation
@example
(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
@end example
-@end quotation
@node Vim mode
@subsection Vim mode
-A Vim mode for entering music and running LilyPond is contained in the
-source archive in @code{$VIM} directory.
+For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
+along with syntax coloring tools. A Vim mode for entering music and
+running LilyPond is contained in the source archive in @code{$VIM}
+directory.
+
+The LilyPond file type is detected if the file
+@file{~/.vim/filetype.vim} has the following content
-The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
-has the following content
-@quotation
@example
if exists("did_load_filetypes")
finish
endif
augroup filetypedetect
- au! BufNewFile,BufRead *.ly setf lilypond
+ au! BufNewFile,BufRead *.ly,*.ily setf lilypond
augroup END
@end example
-@end quotation
Please include this path by appending the following line to your
@file{~/.vimrc}
-@quotation
@example
set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
@end example
-@end quotation
@noindent
-where $@{LILYPOND_VERSION@} is your lilypond version. If Lilypond was not
+where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
installed in @file{/usr/local/}, then change this path accordingly.
+@node jEdit
+@subsection jEdit
+
+Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit}
+text editor, LilyPondTool is the most feature-rich text-based tool for
+editing LilyPond scores. Its features include a Document Wizard with
+lyrics support to set up documents easier, and embedded PDF viewer with
+advanced point-and-click support. For screenshots, demos and
+installation instructions, visit
+@uref{http://lilypondtool@/.organum@/.hu}
+
+
+@node TexShop
+@subsection TexShop
+
+The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
+editor for MacOS@tie{}X can be extended to run LilyPond, lilypond-book and
+convert-ly from within the editor, using the extensions available at
+@uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
+
+
+@node TextMate
+@subsection TextMate
+
+There is a LilyPond bundle for TextMate. It may be installed by running
+
+@example
+mkdir -p /Library/Application\ Support/TextMate/Bundles
+cd /Library/Application\ Support/TextMate/Bundles
+svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
+@end example
+
+
+@node LilyKDE
+@subsection LilyKDE
+
+@uref{http://lilykde.googlecode.com/,LilyKDE} is a plugin for KDE's
+text editor @uref{http://kate-editor.org/,Kate}. It has a powerful Score
+Wizard to quickly setup a LilyPond document and an embedded PDF viewer.
+
+LilyKDE can use @uref{http://www.volny.cz/smilauer/rumor/,Rumor},
+so music can entered by playing on a MIDI keyboard.
+
+Other features are lyric hyphenation and running LilyPond on multiple files
+at once from within the KDE file manager.
+
+
+@node Point and click
+@section Point and click
+@cindex point and click
+
+
+Point and click lets you find notes in the input by clicking on them
+in the PDF viewer. This makes it easier to find input that causes
+some error in the sheet music.
+
+When this functionality is active, LilyPond adds hyperlinks to the PDF
+file. These hyperlinks are sent to the web-browser, which opens a
+text-editor with the cursor in the right place.
+
+To make this chain work, you should configure your PDF viewer to
+follow hyperlinks using the @file{lilypond-invoke-editor} script
+supplied with LilyPond.
+
+For Xpdf on UNIX, the following should be present in
+@file{xpdfrc}@footnote{On UNIX, this file is found either in
+@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
+
+@example
+urlCommand "lilypond-invoke-editor %s"
+@end example
+
+The program @file{lilypond-invoke-editor} is a small helper
+program. It will invoke an editor for the special @code{textedit}
+URIs, and run a web browser for others. It tests the environment
+variable @code{EDITOR} for the following patterns,
+
+@table @code
+@item emacs
+ this will invoke
+@example
+emacsclient --no-wait +@var{line}:@var{column} @var{file}
+@end example
+@item vim
+ this will invoke
+@example
+gvim --remote +:@var{line}:norm@var{char} @var{file}
+@end example
+
+@item nedit
+this will invoke
+@example
+ nc -noask +@var{line} @var{file}'
+@end example
+@end table
+
+The environment variable @code{LYEDITOR} is used to override this. It
+contains the command line to start the editor, where @code{%(file)s},
+@code{%(column)s}, @code{%(line)s} is replaced with the file, column
+and line respectively. The setting
+
+@example
+emacsclient --no-wait +%(line)s:%(column)s %(file)s
+@end example
+
+@noindent
+for @code{LYEDITOR} is equivalent to the standard emacsclient
+invocation.
+
+
+@cindex file size, output
+
+The point and click links enlarge the output files significantly. For
+reducing the size of PDF and PS files, point and click may be switched
+off by issuing
+
+@example
+\pointAndClickOff
+@end example
+
+@noindent
+in a @file{.ly} file. Point and click may be explicitly enabled with
+
+@example
+\pointAndClickOn
+@end example
+
+Alternately, you may disable point and click with a command-line
+option:
+
+@example
+lilypond -dno-point-and-click file.ly
+@end example
+
+@warning{You should always turn off point and click in any LilyPond
+files to be distributed to avoid including path information about
+your computer in the .pdf file, which can pose a security risk.}
projects / lilypond.git / blobdiff