From: Graham Percival Date: Wed, 5 Aug 2009 07:10:19 +0000 (-0700) Subject: Doc: new chapter structuring for Application. X-Git-Tag: release/2.13.4-1~201 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f6e9e17296997924bf0e08e62c9858e2ab14efe0;p=lilypond.git Doc: new chapter structuring for Application. --- diff --git a/Documentation/application.tely b/Documentation/application.tely index b9970f04eb..c1b38b71c6 100644 --- a/Documentation/application.tely +++ b/Documentation/application.tely @@ -119,11 +119,16 @@ More information can be found at of this and other documentation. @c * Install:: How to install or compile. +@c * Setup:: Using LilyPond with other programs. + +@c maybe add a "Tasks" or "Specific tasks" or something like +@c that, after Suggestions -gp @menu -* Setup:: Using LilyPond with other programs. -* Running LilyPond:: Operation. -* LilyPond-book:: Integrating text and music. +* Running lilypond:: Operation. +* Updating files with convert-ly:: Updating input files. +* lilypond-book:: Integrating text and music. * Converting from other formats:: Converting to lilypond source format. +* Suggestions for writing files:: Best practices Appendices @@ -136,10 +141,12 @@ Appendices @c @include application/install.itely -@include application/setup.itely +@c @include application/setup.itely @include application/running.itely +@include application/updating.itely @include application/lilypond-book.itely @include application/converters.itely +@include application/suggestions.itely @include fdl.itexi diff --git a/Documentation/application/converters.itely b/Documentation/application/converters.itely index b3cafb8eac..caa36f50fb 100644 --- a/Documentation/application/converters.itely +++ b/Documentation/application/converters.itely @@ -21,8 +21,8 @@ sequencers and XML converters. Refer to the These are separate programs from @command{lilypond} itself, and are run on the command line; see @ref{Command-line usage} for more information. If you have MacOS 10.3 or 10.4 and you have trouble -running some of these scripts, e.g. @code{convert-ly}, see @ref{Setup -for MacOS X}. +running some of these scripts, e.g. @code{convert-ly}, see +FIXME FIXME @c @ref{Setup for MacOS X}. @knownissues diff --git a/Documentation/application/lilypond-book.itely b/Documentation/application/lilypond-book.itely index ced10dc01f..a7043b4bf9 100644 --- a/Documentation/application/lilypond-book.itely +++ b/Documentation/application/lilypond-book.itely @@ -10,8 +10,8 @@ @c \version "2.12.0" @c Note: keep this node named so that `info lilypond-book' brings you here. -@node LilyPond-book -@chapter @command{lilypond-book}: Integrating text and music +@node lilypond-book +@chapter Running @command{lilypond-book} If you want to add pictures of music to a document, you can simply do it the way you would do with other types of pictures. The pictures are @@ -27,7 +27,7 @@ the music are adjusted to match the layout of your document. This is a separate program from @command{lilypond} itself, and is run on the command line; for more information, see @ref{Command-line usage}. If you have MacOS 10.3 or 10.4 and you have trouble running -@code{lilypond-book}, see @ref{Setup for MacOS X}. +@code{lilypond-book}, see FIXME FIXME @c @ref{Setup for MacOS X}. This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents. diff --git a/Documentation/application/running.itely b/Documentation/application/running.itely index 78e4a72f82..f0b891a80f 100644 --- a/Documentation/application/running.itely +++ b/Documentation/application/running.itely @@ -10,8 +10,8 @@ @c \version "2.12.0" -@node Running LilyPond -@chapter Running LilyPond +@node Running lilypond +@chapter Running @command{lilypond} This chapter details the technicalities of running LilyPond. @@ -19,8 +19,6 @@ This chapter details the technicalities of running LilyPond. * Normal usage:: * Command-line usage:: * Error messages:: -* Updating files with convert-ly:: -* Reporting bugs:: @end menu @@ -44,8 +42,8 @@ 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 @q{command shell}; MacOS@tie{}X users might be more familiar with the terms -@q{terminal} or @q{console}. They should also consult @ref{Setup -for MacOS X}. +@q{terminal} or @q{console}. They should also consult +FIXME @c @ref{Setup for MacOS X}. Describing how to use this part of an operating system is outside the scope of this manual; please consult other documentation on this topic @@ -467,226 +465,4 @@ indicated line of your input file, try checking one or two lines above the indicated position. -@node Updating files with convert-ly -@section Updating files with @command{convert-ly} - -@cindex Updating a LilyPond file -@cindex convert-ly - -The LilyPond input syntax is routinely changed to simplify it or improve -it in different ways. As a side effect of this, the LilyPond interpreter -often is no longer compatible with older input files. To remedy this, -the program @command{convert-ly} can be used to deal with most of the -syntax changes between LilyPond versions. - -@menu -* Invoking convert-ly:: -* Command line options for convert-ly:: -* Problems with convert-ly:: -@end menu - -@node Invoking convert-ly -@subsection Invoking @command{convert-ly} - -@command{convert-ly} uses @code{\version} statements in the input -file to detect the old version number. In most cases, to upgrade -your input file it is sufficient to run - -@example -convert-ly -e myfile.ly -@end example - -@noindent -in the directory containing the file. This will upgrade -@code{myfile.ly} in-place and preserve the original file in -@code{myfile.ly~}. - -To convert all the input files in a directory together use - -@example -convert-ly -e *.ly -@end example - -Alternatively, if you want to specify a different name for the -upgraded file, preserving the original file and name unchanged, -use - -@example -convert-ly myfile.ly > mynewfile.ly -@end example - -@command{convert-ly} always converts up to the last syntax change -handled by it. This means that the @code{\version} number left in -the file is usually lower than the version of @command{convert-ly} -itself. - -The program will list the version numbers for which conversions -have been made. If no version numbers are listed the file is -already up to date. - -@noindent -MacOS@tie{}X users may execute these commands under the menu entry -@code{Compile > Update syntax}. - -Windows users should enter these commands in a Command Prompt window, -which is usually found under -@code{Start > Accessories > Command Prompt}. - -@node Command line options for convert-ly -@subsection Command line options for @command{convert-ly} - -In general, the program is invoked as follows: - -@example -convert-ly [@var{option}]@dots{} @var{filename}@dots{} -@end example - - -The following options can be given: - -@table @code -@item -e,--edit -Apply the conversions direct to the input file, modifying it -in-place. - -@item -f,--from=@var{from-patchlevel} -Set the version to convert from. If this is not set, @command{convert-ly} -will guess this, on the basis of @code{\version} strings in the file. -E.g. @code{--from=2.10.25} - -@item -n,--no-version -Normally, @command{convert-ly} adds a @code{\version} indicator -to the output. Specifying this option suppresses this. - -@item -s, --show-rules -Show all known conversions and exit. - -@item --to=@var{to-patchlevel} -Set the goal version of the conversion. It defaults to the latest -available version. E.g. @code{--to=2.12.2} - -@item -h, --help -Print usage help. -@end table - -To upgrade LilyPond fragments in texinfo files, use - -@example -convert-ly --from=... --to=... --no-version *.itely -@end example - -To see the changes in the LilyPond syntax between two versions, use - -@example -convert-ly --from=... --to=... -s -@end example - - -@node Problems with convert-ly -@subsection Problems with @code{convert-ly} - -When running convert-ly in a Command Prompt window under Windows -on a file which has spaces in the filename or in the path to it, -it is necessary to surround the entire input file name with three -(!) sets of double quotes: - -@example -convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly" -@end example - -If the simple @command{convert-ly -e *.ly} command fails because the -expanded command line becomes too long, the @command{convert-ly} -command may be placed in a loop instead. This example for UNIX -will upgrade all @code{.ly} files in the current directory - -@example -for f in *.ly; do convert-ly -e $f; done; -@end example - -In the Windows Command Prompt window the corresponding command is - -@example -for %x in (*.ly) do convert-ly -e """%x""" -@end example - -Not all language changes are handled. Only one output option can be -specified. Automatically updating scheme and LilyPond scheme -interfaces is quite unlikely; be prepared to tweak scheme code -manually. - -@verbatim -There are a few things that the convert-ly cannot handle. Here's a list -of limitations that the community has complained about. - -This bug report structure has been chosen because convert-ly has a -structure that doesn't allow to smoothly implement all needed changes. -Thus this is just a wishlist, placed here for reference. - -1.6->2.0: - 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 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, - it was possible to group a number of markup commands together within -parentheses, e.g. - -#'((bold italic) "string") - This will incorrectly be converted into - -\markup{{\bold italic} "string"} - instead of the correct - -\markup{\bold \italic "string"} -2.0->2.2: - Doesn't handle \partcombine - Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple -stanzas. -2.0->2.4: - \magnify isn't changed to \fontsize. - - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) - remove-tag isn't changed. - - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . - first-page-number isn't changed. - - first-page-number no => print-first-page-number = ##f - Line breaks in header strings aren't converted. - - \\\\ as line break in \header strings => \markup \center-align < - "First Line" "Second Line" > - Crescendo and decrescendo terminators aren't converted. - - \rced => \! - - \rc => \! -2.2->2.4: - \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly -converted. -2.4.2->2.5.9 - \markup{ \center-align <{ ... }> } should be converted to: - \markup{ \center-align {\line { ... }} } - but now, \line is missing. -2.4->2.6 - Special LaTeX characters such as $~$ in text are not converted to UTF8. -2.8 - \score{} must now begin with a music expression. Anything else - (particularly \header{}) must come after the music. -@end verbatim - - -@node Reporting bugs -@section Reporting bugs - -@cindex bugs -@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, - -@uref{http://code.google.com/p/lilypond/issues/list} - -If you have discovered a bug which is not listed, please report the -bug by following the directions on - -@uref{http://lilypond.org/web/devel/participating/bugs} - -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. - - diff --git a/Documentation/application/suggestions.itely b/Documentation/application/suggestions.itely new file mode 100644 index 0000000000..8157b43112 --- /dev/null +++ b/Documentation/application/suggestions.itely @@ -0,0 +1,15 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@c \version "2.12.0" + +@node Suggestions for writing files +@chapter Suggestions for writing files + + diff --git a/Documentation/application/updating.itely b/Documentation/application/updating.itely new file mode 100644 index 0000000000..7403c56751 --- /dev/null +++ b/Documentation/application/updating.itely @@ -0,0 +1,214 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + +@c \version "2.12.0" + + +@node Updating files with convert-ly +@chapter Updating files with @command{convert-ly} + +@cindex Updating a LilyPond file +@cindex convert-ly + +The LilyPond input syntax is routinely changed to simplify it or improve +it in different ways. As a side effect of this, the LilyPond interpreter +often is no longer compatible with older input files. To remedy this, +the program @command{convert-ly} can be used to deal with most of the +syntax changes between LilyPond versions. + +@menu +* Invoking convert-ly:: +* Command line options for convert-ly:: +* Problems with convert-ly:: +@end menu + +@node Invoking convert-ly +@section Invoking @command{convert-ly} + +@command{convert-ly} uses @code{\version} statements in the input +file to detect the old version number. In most cases, to upgrade +your input file it is sufficient to run + +@example +convert-ly -e myfile.ly +@end example + +@noindent +in the directory containing the file. This will upgrade +@code{myfile.ly} in-place and preserve the original file in +@code{myfile.ly~}. + +To convert all the input files in a directory together use + +@example +convert-ly -e *.ly +@end example + +Alternatively, if you want to specify a different name for the +upgraded file, preserving the original file and name unchanged, +use + +@example +convert-ly myfile.ly > mynewfile.ly +@end example + +@command{convert-ly} always converts up to the last syntax change +handled by it. This means that the @code{\version} number left in +the file is usually lower than the version of @command{convert-ly} +itself. + +The program will list the version numbers for which conversions +have been made. If no version numbers are listed the file is +already up to date. + +@noindent +MacOS@tie{}X users may execute these commands under the menu entry +@code{Compile > Update syntax}. + +Windows users should enter these commands in a Command Prompt window, +which is usually found under +@code{Start > Accessories > Command Prompt}. + +@node Command line options for convert-ly +@section Command line options for @command{convert-ly} + +In general, the program is invoked as follows: + +@example +convert-ly [@var{option}]@dots{} @var{filename}@dots{} +@end example + + +The following options can be given: + +@table @code +@item -e,--edit +Apply the conversions direct to the input file, modifying it +in-place. + +@item -f,--from=@var{from-patchlevel} +Set the version to convert from. If this is not set, @command{convert-ly} +will guess this, on the basis of @code{\version} strings in the file. +E.g. @code{--from=2.10.25} + +@item -n,--no-version +Normally, @command{convert-ly} adds a @code{\version} indicator +to the output. Specifying this option suppresses this. + +@item -s, --show-rules +Show all known conversions and exit. + +@item --to=@var{to-patchlevel} +Set the goal version of the conversion. It defaults to the latest +available version. E.g. @code{--to=2.12.2} + +@item -h, --help +Print usage help. +@end table + +To upgrade LilyPond fragments in texinfo files, use + +@example +convert-ly --from=... --to=... --no-version *.itely +@end example + +To see the changes in the LilyPond syntax between two versions, use + +@example +convert-ly --from=... --to=... -s +@end example + + +@node Problems with convert-ly +@section Problems with @code{convert-ly} + +When running convert-ly in a Command Prompt window under Windows +on a file which has spaces in the filename or in the path to it, +it is necessary to surround the entire input file name with three +(!) sets of double quotes: + +@example +convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly" +@end example + +If the simple @command{convert-ly -e *.ly} command fails because the +expanded command line becomes too long, the @command{convert-ly} +command may be placed in a loop instead. This example for UNIX +will upgrade all @code{.ly} files in the current directory + +@example +for f in *.ly; do convert-ly -e $f; done; +@end example + +In the Windows Command Prompt window the corresponding command is + +@example +for %x in (*.ly) do convert-ly -e """%x""" +@end example + +Not all language changes are handled. Only one output option can be +specified. Automatically updating scheme and LilyPond scheme +interfaces is quite unlikely; be prepared to tweak scheme code +manually. + +@verbatim +There are a few things that the convert-ly cannot handle. Here's a list +of limitations that the community has complained about. + +This bug report structure has been chosen because convert-ly has a +structure that doesn't allow to smoothly implement all needed changes. +Thus this is just a wishlist, placed here for reference. + +1.6->2.0: + 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 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, + it was possible to group a number of markup commands together within +parentheses, e.g. + -#'((bold italic) "string") + This will incorrectly be converted into + -\markup{{\bold italic} "string"} + instead of the correct + -\markup{\bold \italic "string"} +2.0->2.2: + Doesn't handle \partcombine + Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple +stanzas. +2.0->2.4: + \magnify isn't changed to \fontsize. + - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) + remove-tag isn't changed. + - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . + first-page-number isn't changed. + - first-page-number no => print-first-page-number = ##f + Line breaks in header strings aren't converted. + - \\\\ as line break in \header strings => \markup \center-align < + "First Line" "Second Line" > + Crescendo and decrescendo terminators aren't converted. + - \rced => \! + - \rc => \! +2.2->2.4: + \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly +converted. +2.4.2->2.5.9 + \markup{ \center-align <{ ... }> } should be converted to: + \markup{ \center-align {\line { ... }} } + but now, \line is missing. +2.4->2.6 + Special LaTeX characters such as $~$ in text are not converted to UTF8. +2.8 + \score{} must now begin with a music expression. Anything else + (particularly \header{}) must come after the music. +@end verbatim + +