2004-08-27 Han-Wen Nienhuys <hanwen@xs4all.nl>
+ * Documentation/user/point-and-click.texi (Point and click): new file.
+ put point & click in appendix.
+
* Documentation/user/changing-defaults.itely (Vertical spacing):
corrections
@menu
* Setting global staff size::
+* Vertical spacing of piano staves::
* Vertical spacing::
* Horizontal spacing::
* Line breaking::
@tab 12.60
@tab 4.4
@tab
-
+
@item feta14
@tab 14.14
@tab 5.0
-@menu
-* Vertical spacing::
-* Horizontal spacing::
-* Line breaking::
-* Page layout::
-@end menu
-
@node Vertical spacing of piano staves
@subsection Vertical spacing of piano staves
It can be adjusted as follows
@verbatim
\new PianoStaff \with {
- \override VerticalAlignment #'forced-distance = #9
+ \override VerticalAlignment #'forced-distance = #7
} {
...
}
-@end example
-This would bring the staves together at a distance of 9 staff spaces,
+@end verbatim
+This would bring the staves together at a distance of 7 staff spaces,
measured from the center line of each staff.
+The difference is demonstrated in the following example,
+@lilypond[verbatim]
+\relative <<
+ \new PianoStaff \with {
+ \override VerticalAlignment #'forced-distance = #7
+ } <<
+ \new Staff { c1 }
+ \new Staff { c }
+ >>
+ \new PianoStaff <<
+ \new Staff { c }
+ \new Staff { c }
+ >>
+>>
+@end lilypond
+
+
+
+@refbugs
+
+@code{forced-distance} cannot be changed per system.
@node Vertical spacing
@subsection Vertical spacing
c8 c4 c4 c4
@end lilypond
-Normally, @code{spacing-increment} is set to 1.2, which is the
-width of a note head, and @code{shortest-duration-space} is set to
-2.0, meaning that the shortest note gets 2 NHW of space. For normal
-notes, this space is always counted from the left edge of the symbol, so
-the shortest notes are generally followed by one NHW of space.
+Normally, @code{spacing-increment} is set to 1.2 staff space, which is
+approximately the width of a note head, and
+@code{shortest-duration-space} is set to 2.0, meaning that the
+shortest note gets 2.4 staff space (2.0 times the
+@code{spacing-increment}) of horizontal space. This space is counted
+from the left edge of the symbol, so the shortest notes are generally
+followed by one NHW of space.
If one would follow the above procedure exactly, then adding a single
32th note to a score that uses 8th and 16th notes, would widen up the
entire score a lot. The shortest note is no longer a 16th, but a 32nd,
-thus adding 1 NHW to every note. To prevent this, the
-shortest duration for spacing is not the shortest note in the score,
-but the most commonly found shortest note. Notes that are even
-shorter this are followed by a space that is proportional to their
-duration relative to the common shortest note. So if we were to add
-only a few 16th notes to the example above, they would be followed by
-half a NHW:
+thus adding 1 NHW to every note. To prevent this, the shortest
+duration for spacing is not the shortest note in the score, but rather
+the one which occurs most frequently.
-@lilypond[fragment,verbatim,relative=2]
- c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
-@end lilypond
The most common shortest duration is determined as follows: in every
measure, the shortest duration is determined. The most common short
duration, is taken as the basis for the spacing, with the stipulation
that this shortest duration should always be equal to or shorter than
-1/8th note. The shortest duration is printed when you run lilypond
-with @code{--verbose}. These durations may also be customized. If you
-set the @code{common-shortest-duration} in
-@internalsref{SpacingSpanner}, then this sets the base duration for
-spacing. The maximum duration for this base (normally 1/8th), is set
-through @code{base-shortest-duration}.
+1/8th note. The shortest duration is printed when you run
+@code{lilypond} with the @code{--verbose} option.
+
+These durations may also be customized. If you set the
+@code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
+this sets the base duration for spacing. The maximum duration for this
+base (normally 1/8th), is set through @code{base-shortest-duration}.
@cindex @code{common-shortest-duration}
@cindex @code{base-shortest-duration}
@cindex @code{stem-spacing-correction}
@cindex @code{spacing}
-In the Introduction it was explained that stem directions influence
-spacing. This is controlled with @code{stem-spacing-correction}
-property in @internalsref{NoteSpacing}, which are generated for every
+Notes that are even shorter than the commoon shortest note are
+followed by a space that is proportional to their duration relative to
+the common shortest note. So if we were to add only a few 16th notes
+to the example above, they would be followed by half a NHW:
+
+@lilypond[fragment,verbatim,relative=2]
+ c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
+@end lilypond
+
+
+In the introduction (see @ref{Engraving}), it was explained that stem
+directions influence spacing. This is controlled with the
+@code{stem-spacing-correction} property in the
+@internalsref{NoteSpacing}, object. These are generated for every
@internalsref{Voice} context. The @code{StaffSpacing} object
(generated at @internalsref{Staff} context) contains the same property
-for controlling the stem/bar line spacing. The following example
-shows these corrections, once with default settings, and once with
+for controlling the stem/bar line spacing. The following example shows
+these corrections, once with default settings, and once with
exaggerated corrections:
@lilypond[raggedright]
}
@end lilypond
-@cindex SpacingSpanner, overriding properties
-
-Properties of the @internalsref{SpacingSpanner} must be overridden
-from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
-created before any property commands are interpreted.
-@example
-\paper @{ \context @{
- \Score
- \override SpacingSpanner #'spacing-increment = #3.0
-@} @}
-@end example
-
@seealso
No work-around exists for decreasing the amount of space.
+@node Line length
+@subsection Line length
+
+@cindex page breaks
+@cindex breaking pages
+
+@cindex @code{indent}
+@cindex @code{linewidth}
+
+The most basic settings influencing the spacing are @code{indent} and
+@code{linewidth}. They are set in the @code{\paper} block. They
+control the indentation of the first line of music, and the lengths of
+the lines.
+
+If @code{raggedright} is set to true in the @code{\paper}
+block, then the lines are justified at their natural length. This
+useful for short fragments, and for checking how tight the natural
+spacing is.
+
+@cindex page layout
+@cindex vertical spacing
+
+The option @code{raggedlast} is similar to @code{raggedright}, but
+only affects the last line of the piece. No restrictions are put on
+that line. The result is similar to formatting text paragraphs. In a
+paragraph, the last line simply takes its natural length.
+
@node Line breaking
@subsection Line breaking
Internals: @internalsref{BreakEvent}.
-@node Line length and line breaking
-@subsection Line length and line breaking
-
-@cindex page breaks
-@cindex breaking pages
-
-@cindex @code{indent}
-@cindex @code{linewidth}
-
-The most basic settings influencing the spacing are @code{indent} and
-@code{linewidth}. They are set in the @code{\paper} block. They
-control the indentation of the first line of music, and the lengths of
-the lines.
-
-If @code{raggedright} is set to true in the @code{\paper}
-block, then the lines are justified at their natural length. This
-useful for short fragments, and for checking how tight the natural
-spacing is.
-
-@cindex page layout
-@cindex vertical spacing
-
-The option @code{raggedlast} is similar to @code{raggedright}, but
-only affects the last line of the piece. No restrictions are put on
-that line. The result is similar to formatting paragraphs. In a
-paragraph, the last line simply takes its natural length.
@node Multiple movements
@}
@end example
-@node Titling
-@subsection Titling
+@node Creating titles
+@subsection Creating titles
Titles are created for each @code{\score} block, and over a
@code{\book}.
\book {
\header {
title = "Title"
- subtitle = "(and (the) subtitle)"
+ subtitle = "and the subtitle"
subsubtitle = "Sub sub title"
poet = "Poet"
composer = "Composer"
@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
analogous to @code{\break} and @code{\noBreak}. They should be
inserted with a bar line. These commands force and forbid a page-break
-from happening.
+from happening. Of course, the @code{\pageBreak} command also forces
+a line break.
Page breaks are computed by the @code{page-breaking} function in the
@code{\bookpaper} block.
@end example
The second one sets the size of the @code{\paper} block that it is in.
+The following paper sizes are supported.
+
+@table @code
+@item a6
+@item a5
+@item a4
+@item a3
+@item legal
+@item letter
+@item tabloid
+@end table
@node Page layout
@subsection Page layout
The default layout responds to the following settings in the
@code{\bookpaper} block
+
@cindex \bookpaper
@table @code
this boolean controls whether a pagenumber is printed.
@end table
-The page layout itself is done by two functions:
-@code{page-music-height} and @code{page-make-stencil}. The former
-tells the line-breaking algorithm how much space can be spent on a
-page, the latter creates the actual page given the system to put on it.
+The page layout itself is done by two functions in the
+@code{\bookpaper}, @code{page-music-height} and
+@code{page-make-stencil}. The former tells the line-breaking algorithm
+how much space can be spent on a page, the latter creates the actual
+page given the system to put on it.
@seealso
-Examples: @inputfileref{input/test/,page-breaks.ly}
+Examples: @inputfileref{input/test,page-breaks.ly}
@refbugs
* Error messages::
* Reporting bugs::
* Editor support::
-* Point and click::
* Invoking lilypond-latex::
@end menu
block, then the rest of the scores will be output in numbered files,
starting with @file{filename-1.tex}. Several files can be specified;
they will each be processed independently. @footnote{The status of
-GUILE is not reset across invocations, so be careful not to change any
-system defaults from within Scheme.}
+GUILE is not reset after processing a @code{.ly} files, so be careful
+not to change any system defaults from within Scheme.}
@section Command line options
@code{tex} (for @TeX{} output, to be processed with La@TeX{}, and
@code{ps} for PostScript.
-Other output options are intended for developers.
+There are other output options, but they are intended for developers.
@cindex output format, setting
Do not trust the @code{.ly} input.
When LilyPond formatting available through a web server, the
-@code{--safe} @b{MUST} be passed. This will prevent code like
+@code{--safe} @b{MUST} be passed. This will prevent inline Scheme
+code from wreaking havoc, for example
@verbatim
#(system "rm -rf /")
The @code{--safe} option works by evaluating in-line Scheme
expressions in a special safe module. This safe module is derived from
GUILE @file{safe-r5rs} module, but adds a number of functions of the
-LilyPond API. These functions are listed in @file{safe-lily.scm}.
+LilyPond API. These functions are listed in @file{scm/safe-lily.scm}.
In addition, @code{--safe} disallows @code{\include} directives and
disables the use of backslashes in @TeX{} strings.
@end table
-@node Point and click
-@section Point and click
-@cindex point and click
-
-@cindex source specials
-@cindex specials, source
-
-Point and click lets you find notes in the input by clicking on them in
-the Xdvi window. This makes it easier to find input that causes some
-error in the sheet music.
-
-To use it, you need the following software:
-@itemize @bullet
-@item a dvi viewer that supports src specials:
-@itemize @bullet
-@item Xdvi, version 22.36 or newer. Available from
-@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
-
- Most @TeX{} distributions ship with xdvik, which is always a few
-versions behind the official Xdvi. To find out which Xdvi you are
-running, try @code{xdvi -version} or @code{xdvi.bin -version}.
-@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
-newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
-
-Apparently, KDVI does not process PostScript specials correctly. Beams
-and slurs will not be visible in KDVI.
-
-@cindex Xdvi
-@cindex KDVI
-@cindex KDE
-
-
-
-@end itemize
-@item an editor with a client/server interface (or a lightweight GUI
-editor):
-
-@cindex editor
-
-@itemize @bullet
-@item Emacs. Emacs is an extensible text-editor. It is available from
-@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
-column location.
-
-@c move this elsewhere?
-
-
-@cindex Emacs
-@cindex Emacs mode
-@cindex lilypond-mode for Emacs
-@cindex syntax coloring
-
-@item XEmacs. XEmacs is very similar to Emacs.
-
-@cindex XEmacs
-
-@item NEdit. NEdit runs under Windows, and Unix.
- It is available from @uref{http://www.nedit.org}.
-
-@cindex NEdit
-
-@item GVim. GVim is a GUI variant of VIM, the popular VI
-clone. It is available from @uref{http://www.vim.org}.
-
-@cindex GVim
-@cindex Vim
-
-@end itemize
-@end itemize
-
-
-Xdvi must be configured to find the @TeX{} fonts and music
-fonts. Refer to the Xdvi documentation for more information.
-
-To use point-and-click, add one of these lines to the top of your .ly
-file:
-@example
-#(ly:set-point-and-click 'line)
-@end example
-@cindex line-location
-
-When viewing, Control-Mousebutton 1 will take you to the originating
-spot in the @file{.ly} file. Control-Mousebutton 2 will show all
-clickable boxes.
-
-If you correct large files with point-and-click, be sure to start
-correcting at the end of the file. When you start at the top, and
-insert one line, all following locations will be off by a line.
-
-@cindex Emacs
-For using point-and-click with Emacs, add the following
-In your Emacs startup file (usually @file{~/.emacs}):
-@example
-(server-start)
-@end example
-
-Make sure that the environment variable @var{XEDITOR} is set to
-@example
-emacsclient --no-wait +%l %f
-@end example
-@cindex @var{XEDITOR}
-If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
-your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
-
-For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
-use this argument with Xdvi's @code{-editor} option.
-
-@cindex NEdit
-For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
-use this argument with Xdvi's @code{-editor} option.
-
-If can also make your editor jump to the exact location of the note
-you clicked. This is only supported on Emacs and VIM. Users of Emacs version
-20 must apply the patch @file{emacsclient.patch}. Users of version 21
-must apply @file{server.el.patch} (version 21.2 and earlier). At the
-top of the @code{ly} file, replace the @code{set-point-and-click} line
-with the following line:
-@example
-#(ly:set-point-and-click 'line-column)
-@end example
-@cindex line-column-location
-and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
-users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
* Invoking LilyPond:: Operation.
* Converting from other formats:: Converting to lilypond source format.
* Integrating text and music:: Integrating text and music with lilypond-book.
-* Unified index::
+* Literature list::
* Scheme tutorial::
* Notation manual details::
-* Literature list::
-* Cheat sheet::
+* Point and click::
+* Unified index::
* GNU Free Documentation License:: FDL.
+* Cheat sheet::
@end menu
@end ifnottex
@c FIXME: Index has two alphabetically sorted lists @code vs plain?
-@node Unified index
-@unnumbered Unified index
-@printindex cp
+@include literature.itely
@include scheme-tutorial.itely
@include notation-appendices.itely
+@include point-and-click.itely
-@include literature.itely
+@node Unified index
+@appendix Unified index
-@include cheatsheet.itely
+@printindex cp
@include fdl.itexi
+@include cheatsheet.itely
+
@bye
--- /dev/null
+@node Point and click
+@appendix Point and click
+@cindex point and click
+
+@cindex source specials
+@cindex specials, source
+
+Point and click lets you find notes in the input by clicking on them in
+the Xdvi window. This makes it easier to find input that causes some
+error in the sheet music.
+
+To use it, you need the following software:
+@itemize @bullet
+@item a dvi viewer that supports src specials.
+
+The most obvious choice is Xdvi@footnote{KDVI also provides src
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
+specials, but does not use the kpathsea library, so it cannot find
+LilyPond font and PostScript library files.}, version 22.36 or newer.
+It is available from
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
+
+ Most @TeX{} distributions ship with xdvik, which is always a few
+versions behind the official Xdvi. To find out which Xdvi you are
+running, try @code{xdvi -version} or @code{xdvi.bin -version}.
+
+@item an editor with a client/server interface (or a lightweight GUI
+editor):
+
+@cindex editor
+
+@itemize @bullet
+@item Emacs. Emacs is an extensible text-editor. It is available from
+@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
+column location.
+
+@c move this elsewhere?
+
+
+@cindex Emacs
+@cindex Emacs mode
+@cindex lilypond-mode for Emacs
+@cindex syntax coloring
+
+@item XEmacs. XEmacs is very similar to Emacs.
+
+@cindex XEmacs
+
+@item NEdit. NEdit runs under Windows, and Unix.
+ It is available from @uref{http://www.nedit.org}.
+
+@cindex NEdit
+
+@item GVim. GVim is a GUI variant of VIM, the popular VI
+clone. It is available from @uref{http://www.vim.org}.
+
+@cindex GVim
+@cindex Vim
+
+@end itemize
+@end itemize
+
+
+Xdvi must be configured to find the @TeX{} fonts and music
+fonts. Refer to the Xdvi documentation for more information.
+
+To use point-and-click, add one of these lines to the top of your .ly
+file:
+@example
+#(ly:set-point-and-click 'line)
+@end example
+@cindex line-location
+
+When viewing, Control-Mousebutton 1 will take you to the originating
+spot in the @file{.ly} file. Control-Mousebutton 2 will show all
+clickable boxes.
+
+If you correct large files with point-and-click, be sure to start
+correcting at the end of the file. When you start at the top, and
+insert one line, all following locations will be off by a line.
+
+@cindex Emacs
+For using point-and-click with Emacs, add the following
+In your Emacs startup file (usually @file{~/.emacs}):
+@example
+(server-start)
+@end example
+
+Make sure that the environment variable @var{XEDITOR} is set to
+@example
+emacsclient --no-wait +%l %f
+@end example
+@cindex @var{XEDITOR}
+If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
+your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
+
+For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
+use this argument with Xdvi's @code{-editor} option.
+
+@cindex NEdit
+For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
+use this argument with Xdvi's @code{-editor} option.
+
+If can also make your editor jump to the exact location of the note
+you clicked. This is only supported on Emacs and VIM. Users of Emacs version
+20 must apply the patch @file{emacsclient.patch}. Users of version 21
+must apply @file{server.el.patch} (version 21.2 and earlier). At the
+top of the @code{ly} file, replace the @code{set-point-and-click} line
+with the following line:
+@example
+#(ly:set-point-and-click 'line-column)
+@end example
+@cindex line-column-location
+and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
+users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
PACKAGE_NAME=LilyPond
MAJOR_VERSION=2
MINOR_VERSION=3
-PATCH_LEVEL=12
+PATCH_LEVEL=13
MY_PATCH_LEVEL=
pageBreak = #(make-event-chord (list (make-penalty-music -10001 -10001)))
noPageBreak = #(make-event-chord (list (make-penalty-music 0 10001)))
-%% why these defines?
-pagebreak = \pageBreak
-noPagebreak = \noPageBreak
-
noBeam = #(make-music 'BeamForbidEvent)
pipeSymbol = #(make-music 'BarCheck)
projects / lilypond.git / commitdiff