Convert-ly docs

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

diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely
index 88cb790510e2df3fe9657df2493d9196085c5ba3..351e723c65a77d6845499b878f906e760044aef1 100644 (file)
--- a/Documentation/user/running.itely
+++ b/Documentation/user/running.itely
@@ -7,6 +7,8 @@
     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.51"
+

 
 @node Running LilyPond
 @chapter Running LilyPond
 
 @node Running LilyPond
 @chapter Running LilyPond


@@ -15,17 +17,17 @@ This chapter details the technicalities of running LilyPond.
 
 @menu
 * Normal usage::                
 
 @menu
 * Normal usage::                

-* Command-line usage::          
-* Error messages::              
-* Updating files with convert-ly::  
-* Reporting bugs::              
+* Command-line usage::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::

 @end menu
 
 
 @node Normal usage
 @section Normal usage
 
 @end menu
 
 
 @node Normal usage
 @section Normal usage
 

-Most users run LilyPond through a GUI; see @ruser{First steps} if
+Most users run LilyPond through a GUI; see @rlearning{First steps} if

 you have not read this already.
 
 
 you have not read this already.
 
 


@@ -39,15 +41,21 @@ as @code{midi2ly}) which are only available on the command-line.
 
 By @q{command-line}, we mean the command line in the operating system.
 Windows users might be more familiar with the terms @q{DOS shell} or
 
 By @q{command-line}, we mean the command line in the operating system.
 Windows users might be more familiar with the terms @q{DOS shell} or

-@q{command shell}; OSX users might be more familiar with the terms
-@q{terminal} or @q{console}.  OSX users should also consult @ref{MacOS X
+@q{command shell}; MacOS@tie{}X users might be more familiar with the terms
+@q{terminal} or @q{console}.  They should also consult @ref{MacOS X

 on the command-line}.
 
 Describing how to use this part of an operating system is outside the
 scope of this manual; please consult other documentation on this topic
 if you are unfamiliar with the command-line.
 
 on the command-line}.
 
 Describing how to use this part of an operating system is outside the
 scope of this manual; please consult other documentation on this topic
 if you are unfamiliar with the command-line.
 

+@menu
+* Invoking lilypond::
+* Command line options::
+* Environment variables::
+@end menu

 
 

+@node Invoking lilypond

 @subsection Invoking lilypond
 
 @cindex Invoking LilyPond
 @subsection Invoking lilypond
 
 @cindex Invoking LilyPond


@@ -56,7 +64,7 @@ if you are unfamiliar with the command-line.
 @cindex switches
 
 
 @cindex switches
 
 

-The @code{lilypond} executable may be called as follows from the command line.
+The @command{lilypond} executable may be called as follows from the command line.

 
 @example
 lilypond [@var{option}]@dots{} @var{file}@dots{}
 
 @example
 lilypond [@var{option}]@dots{} @var{file}@dots{}


@@ -77,13 +85,13 @@ GUILE is not reset after processing a @code{.ly} file, so be careful
 not to change any system defaults from within Scheme.}
 
 In addition, the value of @code{output-suffix} will be inserted between
 not to change any system defaults from within Scheme.}
 
 In addition, the value of @code{output-suffix} will be inserted between

-the basename and the number.  An input file containing 
+the basename and the number.  An input file containing

 
 @example
 #(define output-suffix "violin")
 
 @example
 #(define output-suffix "violin")

-\book @{ @dots{} @} 
+\book @{ @dots{} @}

 #(define output-suffix "cello")
 #(define output-suffix "cello")

-\book @{ @dots{} @} 
+\book @{ @dots{} @}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -91,7 +99,7 @@ will output @var{base}@file{-violin.ps} and
 @var{base}@file{-cello-1.ps}.
 
 
 @var{base}@file{-cello-1.ps}.
 
 

-
+@node Command line options

 @subsection Command line options
 
 The following options are supported:
 @subsection Command line options
 
 The following options are supported:


@@ -153,7 +161,7 @@ Running @code{lilypond -dhelp} will print all of the @code{-d} options
 available.
 
 @item paper-size
 available.
 
 @item paper-size

-This option sets the default paper-size, 
+This option sets the default paper-size,

 @example
 -dpaper-size=\"letter\"
 @end example
 @example
 -dpaper-size=\"letter\"
 @end example


@@ -232,7 +240,7 @@ This mode is used by default by lilypond-book.
 @cindex SVG (Scalable Vector Graphics)
   You need a SVG viewer which supports embedded fonts, or a SVG
   viewer which is able to replace the embedded fonts with OTF fonts.
 @cindex SVG (Scalable Vector Graphics)
   You need a SVG viewer which supports embedded fonts, or a SVG
   viewer which is able to replace the embedded fonts with OTF fonts.

-  Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
+  Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape}

   (version 0.42 or later), after copying the OTF fonts in directory
   @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
 @item scm
   (version 0.42 or later), after copying the OTF fonts in directory
   @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
 @item scm


@@ -294,19 +302,19 @@ Generate PDF.  This implies @code{--ps}.
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
 
 
 @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}

-Run LilyPond in a chroot jail.
+Run @command{lilypond} in a chroot jail.

 
 The @code{--jail} option provides a more flexible alternative to
 @code{--safe} when LilyPond formatting is available through a web
 server or whenever LilyPond executes externally provided
 sources.
 
 
 The @code{--jail} option provides a more flexible alternative to
 @code{--safe} when LilyPond formatting is available through a web
 server or whenever LilyPond executes externally provided
 sources.
 

-The @code{--jail} option works by changing the root of LilyPond to
+The @code{--jail} option works by changing the root of @command{lilypond} to

 @var{jail} just before starting the actual compilation process.  The user
 and group are then changed to match those provided, and the current
 directory is changed to @var{dir}.  This setup guarantees that it is not
 possible (at least in theory) to escape from the jail.  Note that for
 @var{jail} just before starting the actual compilation process.  The user
 and group are then changed to match those provided, and the current
 directory is changed to @var{dir}.  This setup guarantees that it is not
 possible (at least in theory) to escape from the jail.  Note that for

-@code{--jail} to work LilyPond must be run as root, which is usually
+@code{--jail} to work @command{lilypond} must be run as root, which is usually

 accomplished in a safe way using @command{sudo}.
 
 Setting up a jail is a slightly delicate matter, as we must be sure that
 accomplished in a safe way using @command{sudo}.
 
 Setting up a jail is a slightly delicate matter, as we must be sure that


@@ -324,7 +332,7 @@ mount a loop device.  A separate filesystem also guarantees that LilyPond
 cannot write more space than it is allowed.
 
 @item Setting up a separate user
 cannot write more space than it is allowed.
 
 @item Setting up a separate user

-A separate user and group (say, @samp{lily}/@samp{lily}) with low
+A separate user and group (say, @code{lily}/@code{lily}) with low

 privileges should be used to run LilyPond inside the jail.  There should
 be a single directory writable by this user, which should be passed in
 @var{dir}.
 privileges should be used to run LilyPond inside the jail.  There should
 be a single directory writable by this user, which should be passed in
 @var{dir}.


@@ -364,14 +372,14 @@ Show the warranty with which GNU LilyPond comes. (It comes with
 @strong{NO WARRANTY}!)
 @end table
 
 @strong{NO WARRANTY}!)
 @end table
 

-
+@node Environment variables

 @subsection Environment variables
 
 
 @cindex LANG
 @cindex LILYPOND_DATADIR
 
 @subsection Environment variables
 
 
 @cindex LANG
 @cindex LILYPOND_DATADIR
 

-@code{Lilypond} recognizes the following environment variables:
+@command{lilypond} recognizes the following environment variables:

 @table @code
 @item LILYPOND_DATADIR
 This specifies a directory where locale messages and
 @table @code
 @item LILYPOND_DATADIR
 This specifies a directory where locale messages and


@@ -485,8 +493,8 @@ convert-ly -e myfile.ly
 @end example
 
 @noindent
 @end example
 
 @noindent

-MacOS X users may execute this command under the menu entry
-@samp{Compile > Update syntax}.
+MacOS@tie{}X users may execute this command under the menu entry
+@code{Compile > Update syntax}.

 
 If there are no changes to myfile.ly and file called myfile.ly.NEW
 is created, then myfile.ly is already updated.
 
 If there are no changes to myfile.ly and file called myfile.ly.NEW
 is created, then myfile.ly is already updated.


@@ -510,7 +518,7 @@ convert-ly --from=... --to=... -s
 @end example
 
 To upgrade many files at once, combine @code{convert-ly} with
 @end example
 
 To upgrade many files at once, combine @code{convert-ly} with

-standard unix commands.  This example will upgrade all @code{.ly}
+standard UNIX commands.  This example will upgrade all @code{.ly}

 files in the current directory
 
 @example
 files in the current directory
 
 @example


@@ -559,7 +567,7 @@ Print usage help.
 @subsection Problems with @code{convert-ly}
 
 Not all language changes are handled.  Only one output option can be
 @subsection Problems with @code{convert-ly}
 
 Not all language changes are handled.  Only one output option can be

-specified.  Automatically updating scheme and lilypond scheme
+specified.  Automatically updating scheme and LilyPond scheme

 interfaces is quite unlikely; be prepared to tweak scheme code
 manually.
 
 interfaces is quite unlikely; be prepared to tweak scheme code
 manually.
 


@@ -575,7 +583,7 @@ Thus this is just a wishlist, placed here for reference.
  Doesn't always convert figured bass correctly, specifically things like {<
 >}.  Mats' comment on working around this:
    To be able to run convert-ly
  Doesn't always convert figured bass correctly, specifically things like {<
 >}.  Mats' comment on working around this:
    To be able to run convert-ly

-   on it, I first replaced all occurencies of '{<' to some dummy like '{#'
+   on it, I first replaced all occurrences of '{<' to some dummy like '{#'

    and similarly I replaced '>}' with '&}'.  After the conversion, I could
    then change back from '{ #' to '{ <' and from '& }' to '> }'.
  Doesn't convert all text markup correctly.  In the old markup syntax,
    and similarly I replaced '>}' with '&}'.  After the conversion, I could
    then change back from '{ #' to '{ <' and from '& }' to '> }'.
  Doesn't convert all text markup correctly.  In the old markup syntax,


@@ -625,7 +633,7 @@ converted.
 @cindex reporting bugs
 
 If you have input that results in a crash or an erroneous output, then
 @cindex reporting bugs
 
 If you have input that results in a crash or an erroneous output, then

-that is a bug.  There is a list of current bugs on our google bug tracker,
+that is a bug.  There is a list of current bugs on our Google bug tracker,

 
 @uref{http://code.google.com/p/lilypond/issues/list}
 
 
 @uref{http://code.google.com/p/lilypond/issues/list}
 


@@ -634,7 +642,7 @@ bug by following the directions on
 
 @uref{http://lilypond.org/web/devel/participating/bugs}
 
 
 @uref{http://lilypond.org/web/devel/participating/bugs}
 

-Please construct submit @ruser{Minimal examples}, of bug reports.  We do not
+Please construct and submit minimal examples of bugs in reports.  We do not

 have the resources to investigate reports which are not as small as possible.
 
 
 have the resources to investigate reports which are not as small as possible.