Merge master into nested-bookparts

[lilypond.git] / Documentation / user / setup.itely

diff --git a/Documentation/user/setup.itely b/Documentation/user/setup.itely
index 6d7bca23aa8daca06d49b295aab7614df235efc2..796db8dc4047d71975a3cd57bd60b9d7c6eb98ef 100644 (file)
--- a/Documentation/user/setup.itely
+++ b/Documentation/user/setup.itely
@@ -7,26 +7,63 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.61"
+

 @node Setup
 @chapter Setup
 
 @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
 
 @menu

-* Notes for the MacOS X app::   
+* Setup for specific Operating Systems::  

 * Text editor support::         
 * Point and click::             
 @end menu
 
 
 * Text editor support::         
 * Point and click::             
 @end menu
 
 

-@node Notes for the MacOS X app
-@section Notes for the MacOS X app
+@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
+* 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
+

 
 

-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.
+@subsubheading MacOS X on the command line
+
+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
 
 @example
 @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond


@@ -34,7 +71,7 @@ invoking them directly, e.g.
 
 @noindent
 The same is true of the other scripts in that directory, including
 
 @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,
 
 Alternatively, you may create scripts which add the path
 automatically.  Create a directory to store these scripts,


@@ -89,9 +126,10 @@ There is support from different text editors for LilyPond.
 @menu
 * Emacs mode::                  
 * Vim mode::                    
 @menu
 * Emacs mode::                  
 * Vim mode::                    

-* LilyPondTool::                
+* jEdit::                       

 * TexShop::                     
 * TextMate::                    
 * TexShop::                     
 * TextMate::                    

+* LilyKDE::                     

 @end menu
 
 @node Emacs mode
 @end menu
 
 @node Emacs mode


@@ -147,12 +185,12 @@ set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 @end example
 
 @noindent
 @end example
 
 @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.
 
 
 installed in @file{/usr/local/}, then change this path accordingly.
 
 

-@node LilyPondTool
-@subsection LilyPondTool
+@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
 
 Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit}
 text editor, LilyPondTool is the most feature-rich text-based tool for


@@ -167,7 +205,7 @@ installation instructions, visit
 @subsection TexShop
 
 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}
 @subsection TexShop
 
 The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop}

-editor for Mac OS X can be extended to run LilyPond, lilypond-book and
+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}.
 
 convert-ly from within the editor, using the extensions available at 
 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
 


@@ -184,6 +222,19 @@ svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/
 @end example
 
 
 @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
 
 @node Point and click
 @section Point and click


@@ -195,15 +246,15 @@ 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
 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
+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.
 
 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
+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
 @file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
 
 @example


@@ -211,7 +262,7 @@ urlCommand     "lilypond-invoke-editor %s"
 @end example
 
 The program @file{lilypond-invoke-editor} is a small helper
 @end example
 
 The program @file{lilypond-invoke-editor} is a small helper

-program. It will invoke an editor for the special @code{textedit}
+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,
 
 URIs, and run a web browser for others.  It tests the environment
 variable @code{EDITOR} for the following patterns,
 


@@ -234,10 +285,10 @@ this will invoke
 @end example
 @end table
 
 @end example
 @end table
 

-The environment variable @code{LYEDITOR} is used to override this. It
+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
 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
+and line respectively.  The  setting

 
 @example
 emacsclient --no-wait +%(line)s:%(column)s %(file)s
 
 @example
 emacsclient --no-wait +%(line)s:%(column)s %(file)s


@@ -250,19 +301,28 @@ invocation.
 
 @cindex file size, output
 
 
 @cindex file size, output
 

-The point and click links enlarge the output files significantly. For
+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
 reducing the size of PDF and PS files, point and click may be switched
 off by issuing
 
 @example

-#(ly:set-option 'point-and-click #f)
+\pointAndClickOff

 @end example
 
 @noindent
 @end example
 
 @noindent

-in a @file{.ly} file.  Alternately, you may pass this as an command-line
-option
+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
 
 
 @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.}