Corrections to second round of tutorial rewrite.

[lilypond.git] / Documentation / user / changing-defaults.itely

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index ddd4317ad4cfa94059989f8dabe20d59fcaf4223..d88bf689156c1882bc1a214a95534a4b32af40cc 100644 (file)
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -1,4 +1,12 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c -*- coding: utf-8; mode: texinfo; -*-

+@c This file is part of lilypond.tely
+@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
+

 @node Changing defaults
 @chapter Changing defaults
 
 @node Changing defaults
 @chapter Changing defaults
 


@@ -6,7 +14,7 @@
 The purpose of LilyPond's design is to provide the finest output
 quality as a default.  Nevertheless, it may happen that you need to
 change this default layout.  The layout is controlled through a large
 The purpose of LilyPond's design is to provide the finest output
 quality as a default.  Nevertheless, it may happen that you need to
 change this default layout.  The layout is controlled through a large

-number of proverbial ``knobs and switches.''  This chapter does not
+number of proverbial @q{knobs and switches.}  This chapter does not

 list each and every knob.  Rather, it outlines what groups of controls
 are available and explains how to lookup which knob to use for a
 particular effect.
 list each and every knob.  Rather, it outlines what groups of controls
 are available and explains how to lookup which knob to use for a
 particular effect.


@@ -25,8 +33,8 @@ Program reference manual.
 That manual
 lists all different variables, functions and options available in
 LilyPond.  It is written as a HTML document, which is available
 That manual
 lists all different variables, functions and options available in
 LilyPond.  It is written as a HTML document, which is available

-@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/Documentation/@/user/@/
-lilypond@/-internals/,on@/-line},
+@c leave the @uref as one long line.
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},

 but is also included with the LilyPond documentation package.
 
 There are four areas where the default settings may be changed:
 but is also included with the LilyPond documentation package.
 
 There are four areas where the default settings may be changed:


@@ -48,7 +56,7 @@ notation.  For example, giving each staff a separate time signature.
 @item
 Page layout: changing the appearance of the spacing, line
 breaks, and page dimensions.  These modifications are discussed
 @item
 Page layout: changing the appearance of the spacing, line
 breaks, and page dimensions.  These modifications are discussed

-in @ref{Non-musical notation} and @ref{Page settings}.
+in @ref{Non-musical notation} and @ref{Spacing issues}.

 @end itemize
 
 Internally, LilyPond uses Scheme (a LISP dialect) to provide
 @end itemize
 
 Internally, LilyPond uses Scheme (a LISP dialect) to provide


@@ -84,7 +92,7 @@ beams are automatically displayed.
 Common rules for typesetting accidentals have been placed in a
 function.  This function is called as follows
 
 Common rules for typesetting accidentals have been placed in a
 function.  This function is called as follows
 

-@findex set-accidental-style
+@funindex set-accidental-style

 @example
 #(set-accidental-style 'STYLE #('CONTEXT#))
 @end example
 @example
 #(set-accidental-style 'STYLE #('CONTEXT#))
 @end example


@@ -132,7 +140,7 @@ used by one musician (e.g., a conductor) then
 should be used instead.
 
 @item modern
 should be used instead.
 
 @item modern

-@findex modern style accidentals
+@funindex modern style accidentals

 This rule corresponds to the common practice in the 20th century.  This rule
 prints the same accidentals as @code{default}, but temporary
 accidentals also are canceled in other octaves.  Furthermore,
 This rule corresponds to the common practice in the 20th century.  This rule
 prints the same accidentals as @code{default}, but temporary
 accidentals also are canceled in other octaves.  Furthermore,


@@ -145,8 +153,8 @@ cis' c'' cis'2 | c'' c'
 @end lilypond
 
 @item @code{modern-cautionary}
 @end lilypond
 
 @item @code{modern-cautionary}

-@findex modern-cautionary
-This rule is similar to @code{modern}, but the ``extra'' accidentals
+@funindex modern-cautionary
+This rule is similar to @code{modern}, but the @q{extra} accidentals

 (the ones not typeset by @code{default}) are typeset as cautionary
 accidentals.  They are printed in reduced size or with parentheses
 @lilypond[quote,ragged-right,fragment,verbatim]
 (the ones not typeset by @code{default}) are typeset as cautionary
 accidentals.  They are printed in reduced size or with parentheses
 @lilypond[quote,ragged-right,fragment,verbatim]


@@ -154,14 +162,14 @@ accidentals.  They are printed in reduced size or with parentheses
 cis' c'' cis'2 | c'' c'
 @end lilypond
 
 cis' c'' cis'2 | c'' c'
 @end lilypond
 

-@findex modern-voice
+@funindex modern-voice

 @item modern-voice
 This rule is used for multivoice accidentals to be read both by musicians
 playing one voice and musicians playing all voices.  Accidentals are
 typeset for each voice, but they @emph{are} canceled across voices in
 the same @internalsref{Staff}.
 
 @item modern-voice
 This rule is used for multivoice accidentals to be read both by musicians
 playing one voice and musicians playing all voices.  Accidentals are
 typeset for each voice, but they @emph{are} canceled across voices in
 the same @internalsref{Staff}.
 

-@findex modern-voice-cautionary
+@funindex modern-voice-cautionary

 @item modern-voice-cautionary
 This rule is the same as @code{modern-voice}, but with the extra
 accidentals (the ones not typeset by @code{voice}) typeset
 @item modern-voice-cautionary
 This rule is the same as @code{modern-voice}, but with the extra
 accidentals (the ones not typeset by @code{voice}) typeset


@@ -170,21 +178,21 @@ as cautionaries.  Even though all accidentals typeset by
 some of them are typeset as cautionaries.
 
 @item piano
 some of them are typeset as cautionaries.
 
 @item piano

-@findex piano accidentals
+@funindex piano accidentals

 This rule reflects 20th century practice for piano notation.  Very similar to
 @code{modern} but accidentals also get canceled
 across the staves in the same @internalsref{GrandStaff} or
 @internalsref{PianoStaff}.
 
 @item piano-cautionary
 This rule reflects 20th century practice for piano notation.  Very similar to
 @code{modern} but accidentals also get canceled
 across the staves in the same @internalsref{GrandStaff} or
 @internalsref{PianoStaff}.
 
 @item piano-cautionary

-@findex #(set-accidental-style 'piano-cautionary)
+@funindex #(set-accidental-style 'piano-cautionary)

 Same as @code{#(set-accidental-style 'piano)} but with the extra
 accidentals typeset as cautionaries.
 
 @item no-reset
 Same as @code{#(set-accidental-style 'piano)} but with the extra
 accidentals typeset as cautionaries.
 
 @item no-reset

-@findex no-reset accidental style
+@funindex no-reset accidental style

 This is the same as @code{default} but with accidentals lasting
 This is the same as @code{default} but with accidentals lasting

-``forever'' and not only until the next measure
+@q{forever} and not only until the next measure

 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 #(set-accidental-style 'no-reset)
 c1 cis cis c
 @lilypond[quote,ragged-right,fragment,verbatim,relative=1]
 #(set-accidental-style 'no-reset)
 c1 cis cis c


@@ -192,7 +200,7 @@ c1 cis cis c
 
 @item forget
 This is sort of the opposite of @code{no-reset}: Accidentals
 
 @item forget
 This is sort of the opposite of @code{no-reset}: Accidentals

-are not remembered at all---and hence all accidentals are
+are not remembered at all -- and hence all accidentals are

 typeset relative to the key signature, regardless of what was
 before in the music
 
 typeset relative to the key signature, regardless of what was
 before in the music
 


@@ -224,9 +232,9 @@ problematic notes.
 @node Setting automatic beam behavior
 @subsection Setting automatic beam behavior
 
 @node Setting automatic beam behavior
 @subsection Setting automatic beam behavior
 

-@findex autoBeamSettings
-@findex (end * * * *)
-@findex (begin * * * *)
+@funindex autoBeamSettings
+@funindex (end * * * *)
+@funindex (begin * * * *)

 @cindex automatic beams, tuning
 @cindex tuning automatic beaming
 
 @cindex automatic beams, tuning
 @cindex tuning automatic beaming
 


@@ -355,9 +363,31 @@ In 4/4 time signature, this means that automatic beams could end only on
 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
 3/8, has passed within the measure).
 
 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
 3/8, has passed within the measure).
 

+If any unexpected beam behaviour occurs, check the default automatic beam
+settings in @file{scm/@/auto@/-beam@/.scm}
+for possible interference, because the beam
+endings defined there will still apply on top of your own overrides. Any
+unwanted endings in the default vales must be reverted for your time
+signature(s).
+
+For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin
+with
+
+@example
+%%% revert default values in scm/auto-beam.scm regarding 12/8 time
+#(revert-auto-beam-setting '(end * * 12 8) 3 8)
+#(revert-auto-beam-setting '(end * * 12 8) 3 4)
+#(revert-auto-beam-setting '(end * * 12 8) 9 8)
+
+%%% your new values
+#(override-auto-beam-setting '(end 1 8 12 8) 3 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 7 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 10 8)
+@end example
+

 @cindex automatic beam generation
 @cindex autobeam
 @cindex automatic beam generation
 @cindex autobeam

-@findex autoBeaming
+@funindex autoBeaming

 @cindex lyrics
 
 If beams are used to indicate melismata in songs, then automatic
 @cindex lyrics
 
 If beams are used to indicate melismata in songs, then automatic


@@ -366,11 +396,23 @@ beaming should be switched off with @code{\autoBeamOff}.
 
 @refcommands
 
 
 @refcommands
 

-@findex \autoBeamOff
+@funindex \autoBeamOff

 @code{\autoBeamOff},
 @code{\autoBeamOff},

-@findex \autoBeamOn
+@funindex \autoBeamOn

 @code{\autoBeamOn}.
 
 @code{\autoBeamOn}.
 

+@commonprop
+
+Beaming patterns may be altered with the @code{beatGrouping} property,
+
+@lilypond[quote,verbatim,relative=2,fragment,ragged-right]
+\time 5/16
+\set beatGrouping = #'(2 3)
+c8[^"(2+3)" c16 c8]
+\set beatGrouping = #'(3 2)
+c8[^"(3+2)" c16 c8]
+@end lilypond
+

 
 @refbugs
 
 
 @refbugs
 


@@ -394,6 +436,7 @@ This section describes what contexts are, and how to modify them.
 * Layout tunings within contexts::  
 * Changing context default settings::  
 * Defining new contexts::       
 * Layout tunings within contexts::  
 * Changing context default settings::  
 * Defining new contexts::       

+* Aligning contexts::           

 @end menu
 
 
 @end menu
 
 


@@ -473,7 +516,7 @@ create them by hand.  There are three commands that do this.
 The easiest command is @code{\new}, and it also the quickest to type.
 It is prepended to a music expression, for example
 
 The easiest command is @code{\new}, and it also the quickest to type.
 It is prepended to a music expression, for example
 

-@findex \new
+@funindex \new

 @cindex new contexts
 @cindex Context, creating
 
 @cindex new contexts
 @cindex Context, creating
 


@@ -506,7 +549,7 @@ However, this user specified name is only used if there is no other
 context already earlier with the same name.
 
 
 context already earlier with the same name.
 
 

-@findex \context
+@funindex \context

 
 @item
 Like @code{\new}, the @code{\context} command also directs a music
 
 @item
 Like @code{\new}, the @code{\context} command also directs a music


@@ -592,8 +635,8 @@ To have it interpreted at the @context{Score} or @context{Staff} level use
 these forms
 
 @example
 these forms
 
 @example

-\context \applyOutput #'Score #@var{function}
-\context \applyOutput #'Staff #@var{function}
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}

 @end example
 
 @end itemize
 @end example
 
 @end itemize


@@ -603,7 +646,7 @@ these forms
 @subsection Changing context properties on the fly
 
 @cindex properties
 @subsection Changing context properties on the fly
 
 @cindex properties

-@findex \set
+@funindex \set

 @cindex changing properties
 
 Each context can have different @emph{properties}, variables contained
 @cindex changing properties
 
 Each context can have different @emph{properties}, variables contained


@@ -652,10 +695,10 @@ R1*2
 Contexts are hierarchical, so if a bigger context was specified, for
 example @context{Staff}, then the change would also apply to all
 @context{Voice}s in the current stave.  The change is applied
 Contexts are hierarchical, so if a bigger context was specified, for
 example @context{Staff}, then the change would also apply to all
 @context{Voice}s in the current stave.  The change is applied

-`on-the-fly', during the music, so that the setting only affects the
+@q{on-the-fly}, during the music, so that the setting only affects the

 second group of eighth notes.
 
 second group of eighth notes.
 

-@findex \unset
+@funindex \unset

 
 There is also an @code{\unset} command,
 @example
 
 There is also an @code{\unset} command,
 @example


@@ -728,7 +771,7 @@ Translation @arrow{} Tunable context properties.
 
 Notation contexts (like @code{Score} and @code{Staff}) not only
 store properties,
 
 Notation contexts (like @code{Score} and @code{Staff}) not only
 store properties,

-they also contain plug-ins called ``engravers'' that create notation
+they also contain plug-ins called @q{engravers} that create notation

 elements.  For example, the @code{Voice} context contains a
 @code{Note_head_engraver} and the @code{Staff} context contains a
 @code{Key_signature_engraver}.
 elements.  For example, the @code{Voice} context contains a
 @code{Note_head_engraver} and the @code{Staff} context contains a
 @code{Key_signature_engraver}.


@@ -754,7 +797,7 @@ It can be useful to shuffle around these plug-ins.  This is done by
 starting a new context with @code{\new} or @code{\context}, and
 modifying it,
 
 starting a new context with @code{\new} or @code{\context}, and
 modifying it,
 

-@findex \with
+@funindex \with

 
 @example
 \new @var{context} \with @{
 
 @example
 \new @var{context} \with @{


@@ -844,7 +887,7 @@ The syntax for this is
 
 Here @var{name} is the name of a graphical object, like @code{Stem} or
 @code{NoteHead}, and @var{property} is an internal variable of the
 
 Here @var{name} is the name of a graphical object, like @code{Stem} or
 @code{NoteHead}, and @var{property} is an internal variable of the

-formatting system (`grob property' or `layout property').  The latter is a
+formatting system (@q{grob property} or @q{layout property}).  The latter is a

 symbol, so it must be quoted.  The subsection @ref{Constructing a
 tweak} explains what to fill in for @var{name}, @var{property}, and
 @var{value}.  Here we only discuss the functionality of this command.
 symbol, so it must be quoted.  The subsection @ref{Constructing a
 tweak} explains what to fill in for @var{name}, @var{property}, and
 @var{value}.  Here we only discuss the functionality of this command.


@@ -910,7 +953,7 @@ affects settings that were made in the same context.  In other words, the
 \revert Staff.Stem #'thickness
 @end example
 
 \revert Staff.Stem #'thickness
 @end example
 

-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside

 properties.  To tweak those, use commands of the form
 
 @c leave this as a long long
 properties.  To tweak those, use commands of the form
 
 @c leave this as a long long


@@ -1125,7 +1168,7 @@ Put together, we get
 @}
 @end example
 
 @}
 @end example
 

-@findex \accepts
+@funindex \accepts

 Contexts form hierarchies.  We want to hang the @context{ImproVoice}
 under @context{Staff}, just like normal @code{Voice}s.  Therefore, we
 modify the @code{Staff} definition with the @code{\accepts}
 Contexts form hierarchies.  We want to hang the @context{ImproVoice}
 under @context{Staff}, just like normal @code{Voice}s.  Therefore, we
 modify the @code{Staff} definition with the @code{\accepts}


@@ -1138,7 +1181,7 @@ command,
 @}
 @end example
 
 @}
 @end example
 

-@findex \denies
+@funindex \denies

 The opposite of @code{\accepts} is @code{\denies},
 which is sometimes needed when reusing existing context definitions.
 
 The opposite of @code{\accepts} is @code{\denies},
 which is sometimes needed when reusing existing context definitions.
 


@@ -1172,6 +1215,30 @@ Then the output at the start of this subsection can be entered as
 @end example
 
 
 @end example
 
 

+@node Aligning contexts
+@subsection Aligning contexts
+
+New contexts may be aligned above or below exisiting contexts.  This
+could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+in ossia,
+
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
+
+@lilypond[quote,ragged-right]
+ossia = { f4 f f f }
+\score{
+  \relative c' \new Staff = "main" {
+    c4 c c c
+    <<
+      \new Staff \with {alignAboveContext=main} \ossia
+      { d8 f d f d f d f }
+    >>
+  }
+}
+@end lilypond
+

 
 
 @node The \override command
 
 
 @node The \override command


@@ -1213,7 +1280,7 @@ This means that we must determine these bits of information:
 @item a sensible value: here @code{3.0}.
 @end itemize
 
 @item a sensible value: here @code{3.0}.
 @end itemize
 

-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside

 properties.  To tweak those, use commands in the form
 
 @example
 properties.  To tweak those, use commands in the form
 
 @example


@@ -1224,7 +1291,7 @@ properties.  To tweak those, use commands in the form
 @cindex finding graphical objects
 @cindex graphical object descriptions
 @cindex tweaking
 @cindex finding graphical objects
 @cindex graphical object descriptions
 @cindex tweaking

-@findex \override
+@funindex \override

 @cindex internal documentation
 
 We demonstrate how to glean this information from the notation manual
 @cindex internal documentation
 
 We demonstrate how to glean this information from the notation manual


@@ -1402,13 +1469,13 @@ This object supports the following interfaces:
 
 Clicking any of the links will take you to the page of the respective
 object interface.  Each interface has a number of properties.  Some of
 
 Clicking any of the links will take you to the page of the respective
 object interface.  Each interface has a number of properties.  Some of

-them are not user-serviceable (``Internal properties''), but others
+them are not user-serviceable (@q{Internal properties}), but others

 can be modified.
 
 We have been talking of @emph{the} @code{Fingering} object, but actually it
 does not amount to much.  The initialization file (see
 @ref{Default files})
 can be modified.
 
 We have been talking of @emph{the} @code{Fingering} object, but actually it
 does not amount to much.  The initialization file (see
 @ref{Default files})

-@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},

 
 @example
 (Fingering
 
 @example
 (Fingering


@@ -1507,7 +1574,7 @@ Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
 @node Objects connected to the input
 @subsection Objects connected to the input
 
 @node Objects connected to the input
 @subsection Objects connected to the input
 

-@findex \tweak
+@funindex \tweak

 
 In some cases, it is possible to take a short-cut for tuning graphical
 objects. For objects that result directly from a piece of the input,
 
 In some cases, it is possible to take a short-cut for tuning graphical
 objects. For objects that result directly from a piece of the input,


@@ -1570,7 +1637,7 @@ this.  Context properties are modified with @code{\set}.
 There is a special type of context property: the element
 description. These properties are named in @code{StudlyCaps}
 (starting with capital letters).  They contain the
 There is a special type of context property: the element
 description. These properties are named in @code{StudlyCaps}
 (starting with capital letters).  They contain the

-``default settings'' for said graphical object as an
+@q{default settings} for said graphical object as an

 association list.  See @file{scm/@/define@/-grobs@/.scm}
 to see what kind of settings there are.  Element descriptions
 may be modified with @code{\override}.
 association list.  See @file{scm/@/define@/-grobs@/.scm}
 to see what kind of settings there are.  Element descriptions
 may be modified with @code{\override}.


@@ -1591,7 +1658,7 @@ is more or less equivalent to
 
 The value of @code{context} (the alist) is used to initalize
 the properties of individual grobs.  Grobs also have
 
 The value of @code{context} (the alist) is used to initalize
 the properties of individual grobs.  Grobs also have

-properties, named in scheme style, with
+properties, named in Scheme style, with

 @code{dashed-words}.  The values of grob properties change
 during the formatting process: formatting basically amounts
 to computing properties using callback functions.
 @code{dashed-words}.  The values of grob properties change
 during the formatting process: formatting basically amounts
 to computing properties using callback functions.