A whole bunch of minor fixes from mailist.

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

diff --git a/Documentation/user/invoking.itely b/Documentation/user/invoking.itely
index 08a4d79e94e2962b0a599886f483ef401f6dfea4..9cfb8b18d972a8bb9af09a9d6ac8b8e96aa0b51f 100644 (file)
--- a/Documentation/user/invoking.itely
+++ b/Documentation/user/invoking.itely
@@ -7,6 +7,7 @@ This chapter details the technicalities of running LilyPond.
 
 @menu
 * Invoking lilypond::           
+* Notes for the MacOS X app::   
 * Error messages::              
 * Updating files with convert-ly::  
 * Reporting bugs::              
@@ -51,7 +52,24 @@ The following options are supported:
 @item -e,--evaluate=@var{expr}
 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
 Multiple @code{-e} options may be given, they will be evaluated
-sequentially.  
+sequentially.
+
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
+
+@example
+lilypond -e '(define-public a 42)'
+@end example
+
+@noindent
+on the command-line, and include
+
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+at the top of the @code{.ly} file. 
 
 @item -f,--format=@var{format}
 which formats should be written.  Choices are @code{svg}, @code{ps},
@@ -120,6 +138,9 @@ available, and exit.
 @item -h,--help
 Show a summary of usage.
 
+@item -H,--header=FIELD
+Dump a header field to file BASENAME.FIELD
+
 @item --include, -I=@var{directory}
 Add @var{directory} to the search path for input files.
 @cindex file searching
@@ -297,6 +318,30 @@ uses more CPU time. The default value is @code{70}.
 @end table
 
 
+@node Notes for the MacOS X app
+@section Notes for the MacOS X app
+
+The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
+included inside MacOS X .app. They can be run from the command line by
+invoking them directly, e.g. 
+
+@example
+@var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
+@end example 
+
+Alternatively, you may add this directory to your path.  Modify (or create)
+a file called @code{.profile} in your home directory such that it contains
+
+@example
+export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
+@end example
+
+@noindent
+This file should end with a blank line.
+
+Note that @var{path/to} will generally be @code{/Applications/}.
+
+
 @node Error messages
 @section Error messages
 
@@ -522,14 +567,25 @@ here for reference.
 If you have input that results in a crash or an erroneous output, then
 that is a bug.  We try to respond to bug-reports promptly, and fix them as
 soon as possible.  Help us by sending a defective input file, so we can
-reproduce the problem.  Make it small, so we can easily debug the
-problem.  Don't forget to tell which version of LilyPond you use!  Send
-the report via
+reproduce the problem. Send the report via:
 
 @example
 @uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
 @end example
 
+A few tips:
+@itemize @bullet
+
+@item Try to produce a very small input file which demonstrates the problem;
+one or two bars is often sufficient to reproduce a bug. The smaller the
+input file is, the easier it is for us to debug the problem.
+
+@item Don't forget to tell which version of LilyPond you use!
+
+@item If possible, use @code{ragged-right} in your example. This makes sure
+that the bug can be reproduced in all paper sizes.
+@end itemize
+
 @ignore
 @c the bug database is not up to date enough. 
 
@@ -542,20 +598,21 @@ been reported and a fix or workaround is already known.
 
 Here is an example of a good bug report:
 
-@example
+@verbatim
 It seems that placement of accidentals is broken.  In the
 following example, the accidental touches the note head.
 
 Using Mac OSX 10.3.7, fink package lilypond-devel
 
 \version "2.7.32"
-\relative c''@{
+\layout { ragged-right = ##t }
+\relative c'' {
    a4 b cis d
-@}
-@end example
+}
+@end verbatim
 
 @lilypond[quote]
-\version "2.7.32"
+\layout { ragged-right = ##t }
 \relative c''{
   \override Accidental #'extra-offset = #'(1.0 . 0)
   a4 b cis d