From bda363653312985bbb7e21c3037df218d7ec4ed9 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Tue, 16 Oct 2007 13:30:59 -0700 Subject: [PATCH] Misc Learning Manual organization. --- Documentation/user/lilypond-learning.tely | 4 +- Documentation/user/putting.itely | 13 +-- Documentation/user/tutorial.itely | 8 +- Documentation/user/tweaks.itely | 118 ++++++++++++---------- Documentation/user/working.itely | 45 +++++---- 5 files changed, 103 insertions(+), 85 deletions(-) diff --git a/Documentation/user/lilypond-learning.tely b/Documentation/user/lilypond-learning.tely index fe36740aff..ffd2e42149 100644 --- a/Documentation/user/lilypond-learning.tely +++ b/Documentation/user/lilypond-learning.tely @@ -131,8 +131,8 @@ of this and other documentation. * Introduction:: What, Why, How. * Tutorial:: A tutorial introduction. * Putting it all together:: More explanation about LilyPond concepts. -* Working on LilyPond projects:: Discusses real-life usage. * Tweaking output:: Introduction to modifying output. +* Working on LilyPond projects:: Discusses real-life usage. Appendices @@ -153,8 +153,8 @@ Appendices @include tutorial.itely @include fundamental.itely @include putting.itely -@include working.itely @include tweaks.itely +@include working.itely @include templates.itely @include scheme-tutorial.itely diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely index b1a5dfa976..6ed4cebd04 100644 --- a/Documentation/user/putting.itely +++ b/Documentation/user/putting.itely @@ -29,7 +29,7 @@ want something that isn't covered? @menu * Soprano and cello:: -* Another example of extending templates:: +* TODO another example of extending templates:: @end menu @node Soprano and cello @@ -214,8 +214,8 @@ celloMusic = \relative c { @end lilypond -@node Another example of extending templates -@unnumberedsubsec Another example of extending templates +@node TODO another example of extending templates +@unnumberedsubsec TODO another example of extending templates TODO: somebody else fill this in. You guys like vocal stuff, right? Get to it. :) -gp @@ -346,11 +346,4 @@ leading to >> @end lilypond -More in-depth information on preparing parts and scores can be found -in the notation manual; see @ruser{Orchestral music}. - -Setting run-time variables (@q{properties}) is discussed in -@ruser{Changing context properties on the fly}. - - diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 6dd6725a12..f0d8a2c300 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -10,9 +10,9 @@ @ignore Tutorial guidelines: (different from policy.txt!) - unless you have a really good reason, use either - @l ilypond[verbatim,quote,ragged-right] + @lilypond[verbatim,quote,ragged-right] or - @l ilypond[verbatim,quote,ragged-right,fragment,relative=2] +blah @lilypond[verbatim,quote,ragged-right,fragment,relative=2] f (without spaces) Don't use any other relative=X commands (make it a non-fragment example), and don't use fragment without relative=2. @@ -21,6 +21,10 @@ Tutorial guidelines: (different from policy.txt!) until we get to the Basic notation chapter. - Add "Music glossary: @r gloss{foo}" to the _top_ of the relevant portions of the tutorial. +@node foo +@section foo + +blah @end ignore diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index 70e0bffb88..fc51023e7d 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -13,28 +13,33 @@ This chapter discusses how to modify output. LilyPond is extremely configurable; virtually every fragment of output may be changed. +TODO: explain what/why. maybe in other sections. + +@menu +* Common tweaks:: +* TODO other name:: +@end menu + + +@node Common tweaks +@section Common tweaks + +blah blah @menu * Moving objects:: * Fixing overlapping notation:: -* Common tweaks:: -* Default files:: +* Other common tweaks:: * Fitting music onto fewer pages:: -* Advanced tweaks with Scheme:: -* Avoiding tweaks with slower processing:: @end menu - @node Moving objects -@section Moving objects +@subsection Moving objects This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. This is unfortunate, but (in most cases) is easily solved. -@c FIXME: find a better example for 5.1 Moving Objects. -gp -@c yes, I want this TODO to be visible to end-users. It's better -@c than having nothing at all. TODO: with the new spacing features in 2.12, these specific examples are no longer relevant. However, they still demonstrate powerful features of lilypond, so they remain until somebody creates some better examples. @@ -157,13 +162,13 @@ c4^"piu mosso" d e f @seealso -This manual: @ruser{The \override command}, @ruser{Common tweaks}. +This manual: @ruser{The \override command}, @ref{Common tweaks}. @node Fixing overlapping notation -@section Fixing overlapping notation +@subsection Fixing overlapping notation -In @ruser{Moving objects}, we saw how to move a @code{TextScript} +In @ref{Moving objects}, we saw how to move a @code{TextScript} object. The same mechanism can be used to move other types of objects; simply replace @code{TextScript} with the name of another object. @@ -203,8 +208,8 @@ common objects. @end multitable -@node Common tweaks -@section Common tweaks +@node Other common tweaks +@subsection Other common tweaks Some overrides are so common that predefined commands are provided as short-cuts, such as @code{\slurUp} and @code{\stemDown}. These @@ -333,42 +338,8 @@ are measured in staff-spaces. For more information, see the relevant portion of the program reference. -@node Default files -@section Default files - -The Program Reference documentation contains a lot of information -about LilyPond, but even more information can be gathered from -looking at the internal LilyPond files. - -Some default settings (such as the definitions for -@code{\header@{@}}s) are stored as @code{.ly} files. Other -settings (such as the definitions of markup commands) are -stored as @code{.scm} (Scheme) files. Further explanation is -outside the scope of this manual; users should be warned that -a substantial amount of technical knowledge or time is required -to understand these files. - -@itemize - -@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/} - -@item OSX: -@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}. -To access this, either @code{cd} into this directory from the -Terminal, or control-click on the LilyPond application and select -@q{Show Package Contents}. - -@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/} - -@end itemize - -The @file{ly/} and @file{scm/} directories will be of -particular interest. Files such as @file{ly/property-init.ly} and -@file{ly/declarations-init.ly} define all the common tweaks. - - @node Fitting music onto fewer pages -@section Fitting music onto fewer pages +@subsection Fitting music onto fewer pages Sometimes you can end up with one or two staves on a second (or third, or fourth...) page. This is annoying, especially @@ -454,14 +425,57 @@ Alter the horizontal spacing via @code{SpacingSpanner}. See @end itemize +@node TODO other name +@section TODO other name + +@menu +* Default files:: +* Advanced tweaks with Scheme:: +* Avoiding tweaks with slower processing:: +@end menu + +@node Default files +@subsection Default files + +The Program Reference documentation contains a lot of information +about LilyPond, but even more information can be gathered from +looking at the internal LilyPond files. + +Some default settings (such as the definitions for +@code{\header@{@}}s) are stored as @code{.ly} files. Other +settings (such as the definitions of markup commands) are +stored as @code{.scm} (Scheme) files. Further explanation is +outside the scope of this manual; users should be warned that +a substantial amount of technical knowledge or time is required +to understand these files. + +@itemize + +@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/} + +@item OSX: +@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}. +To access this, either @code{cd} into this directory from the +Terminal, or control-click on the LilyPond application and select +@q{Show Package Contents}. + +@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/} + +@end itemize + +The @file{ly/} and @file{scm/} directories will be of +particular interest. Files such as @file{ly/property-init.ly} and +@file{ly/declarations-init.ly} define all the common tweaks. + + @node Advanced tweaks with Scheme -@section Advanced tweaks with Scheme +@subsection Advanced tweaks with Scheme We have seen how LilyPond output can be heavily modified using commands like @code{\override TextScript #'extra-offset = ( 1 . -1)}. But we have even more power if we use Scheme. For a full explantion -of this, see the @ruser{Scheme tutorial}, and +of this, see the @ref{Scheme tutorial}, and @ruser{Interfaces for programmers}. We can use Scheme to simply @code{\override} commands, @@ -515,7 +529,7 @@ pattern = #(define-music-function (parser location x y) (ly:music? ly:music?) @node Avoiding tweaks with slower processing -@section Avoiding tweaks with slower processing +@subsection Avoiding tweaks with slower processing LilyPond can perform extra checks while it processes files. These commands will take extra time, but the result may require fewer diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely index 26b1fc6214..c4ccf5dce8 100644 --- a/Documentation/user/working.itely +++ b/Documentation/user/working.itely @@ -18,11 +18,7 @@ this chapter. @menu * Suggestions for writing LilyPond files:: -* Saving typing with variables and functions:: -* Style sheets:: -* Updating old files:: -* Troubleshooting (taking it all apart):: -* Minimal examples:: +* When things don't work:: @end menu @@ -59,6 +55,8 @@ structured in order to be easier (or header) to update. * General suggestions:: * Typesetting existing music:: * Large projects:: +* Saving typing with variables and functions:: +* Style sheets:: @end menu @@ -110,8 +108,8 @@ phrase (instead of just @code{c d e}) you can save yourself some problems if you rearrange your music later. @item @strong{Separate tweaks} from music definitions. See -@ruser{Saving typing with variables and functions}, and -@ruser{Style sheets}. +@ref{Saving typing with variables and functions}, and +@ref{Style sheets}. @end itemize @@ -170,7 +168,7 @@ g4 c'8. e16 @end example @item @strong{Separate tweaks from music definitions}. This -point was made in @ruser{General suggestions}, but for large +point was made in previously, but for large projects it is absolutely vital. We might need to change the definition of @code{fthenp}, but then we only need to do this once, and we can still avoid touching anything @@ -188,7 +186,7 @@ g4\fthenp c'8. e16 @node Saving typing with variables and functions -@section Saving typing with variables and functions +@subsection Saving typing with variables and functions @cindex variables @cindex variables @@ -284,25 +282,25 @@ padText = @end lilypond Using variables is also a good way to reduce work if the -LilyPond input syntax changes (see @ruser{Updating old files}). If +LilyPond input syntax changes (see @ref{Updating old files}). If you have a single definition (such as @code{\dolce}) for all your -files (see @ruser{Style sheets}), then if the syntax changes, you +files (see @ref{Style sheets}), then if the syntax changes, you only need to update your single @code{\dolce} definition, instead of making changes throughout every @code{.ly} file. @node Style sheets -@section Style sheets +@subsection Style sheets The output that LilyPond produces can be heavily modified; see -@ruser{Tweaking output}, for details. But what if you have many +@ref{Tweaking output}, for details. But what if you have many files that you want to apply your tweaks to? Or what if you simply want to separate your tweaks from the actual music? This is quite easy to do. Let's look at an example. Don't worry if you don't understand the parts with all the @code{#()}. This is explained in -@ruser{Advanced tweaks with Scheme}. +@ref{Advanced tweaks with Scheme}. @lilypond[quote,verbatim,ragged-right] mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0) @@ -323,7 +321,7 @@ tempoMark = #(define-music-function (parser location markp) (string?) @end lilypond There are some problems with overlapping output; we'll fix those using -the techniques in @ruser{Moving objects}. But let's also +the techniques in @ref{Moving objects}. But let's also do something about the @code{mpdolce} and @code{tempoMark} definitions. They produce the output we desire, but we might want to use them in another piece. We could simply copy-and-paste them @@ -546,8 +544,17 @@ file with @code{\include "../global.ly"}, which contains @end example +@node When things don't work +@section When things don't work + +@menu +* Updating old files:: +* Troubleshooting (taking it all apart):: +* Minimal examples:: +@end menu + @node Updating old files -@section Updating old files +@subsection Updating old files The LilyPond input syntax occasionally changes. As LilyPond itself improves, the syntax (input language) is modified accordingly. Sometimes @@ -575,7 +582,7 @@ your old LilyPond files. @node Troubleshooting (taking it all apart) -@section Troubleshooting (taking it all apart) +@subsection Troubleshooting (taking it all apart) Sooner or later, you will write a file that LilyPond cannot compile. The messages that LilyPond gives may help @@ -626,11 +633,11 @@ Now start slowly uncommenting more and more of the @code{bass} part until you find the problem line. Another very useful debugging technique is constructing -@ruser{Minimal examples}. +@ref{Minimal examples}. @node Minimal examples -@section Minimal examples +@subsection Minimal examples A minimal example is an example which is as small as possible. These examples are much easier to understand than long examples. Minimal -- 2.39.5