Doc-de: update macros.itely and nitpicks

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

diff --git a/Documentation/user/setup.itely b/Documentation/user/setup.itely
index 1daccd6b6d0c8a54f52a735ed626b9c0a28756fc..da5bbe90ae5c2dc94b4bd02befdd168c31aa78bf 100644 (file)
--- a/Documentation/user/setup.itely
+++ b/Documentation/user/setup.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.12.0"
 
 @node Setup
 @chapter Setup
@@ -17,9 +17,9 @@ 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::             
+* Setup for specific Operating Systems::
+* Text editor support::
+* Point and click::
 @end menu
 
 
@@ -30,15 +30,39 @@ This section explains how to perform additional setup for specific
 operating systems.
 
 @menu
-* MacOS X on the command-line::  
+* Setup for MacOS X::
 @end menu
 
+@node Setup for MacOS X
+@subsection Setup for MacOS X
 
-@node MacOS X on the command-line
-@subsection MacOS X on the command-line
+@subsubheading Using Python scripts on MacOS 10.3 or 10.4
 
-The scripts (such as lilypond-book, convert-ly, abc2ly, and even
-lilypond itself) are included inside the .app file for MacOS@tie{}X.  They can be run from
+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
+
+
+@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
@@ -47,7 +71,7 @@ the command line by invoking them directly, e.g.
 
 @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,
@@ -100,12 +124,12 @@ Note that @var{path/to} will generally be @code{/Applications/}.
 There is support from different text editors for LilyPond.
 
 @menu
-* Emacs mode::                  
-* Vim mode::                    
-* jEdit::                       
-* TexShop::                     
-* TextMate::                    
-* LilyKDE::                     
+* Emacs mode::
+* Vim mode::
+* jEdit::
+* TexShop::
+* TextMate::
+* LilyKDE::
 @end menu
 
 @node Emacs mode
@@ -149,7 +173,7 @@ 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
 
@@ -182,7 +206,7 @@ installation instructions, visit
 
 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 
+convert-ly from within the editor, using the extensions available at
 @uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}.
 
 
@@ -282,14 +306,23 @@ 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
-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
 
+@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.}