From 06ba37b9fc842694c68d68fe762ef1ce60bb3fda Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Wed, 20 Jan 2010 21:29:09 +0000 Subject: [PATCH] Doc: new chapter "External programs" in Usage. This consists of the old "Converting from other formats" chapter, plus the "Point and click" and "Text editor support" from the Running lilypond chapter; all of these kind-of stuck out awkwardly. No nodes were harmed (renamed) in the making of this patch so far. "Running lilypond-book"'s "Alternate methods..." has been moved into External programs, with the new name of "LilyPond output in other programs". The old name still exists for ease of TOC and whatnot, but anybody referring to it might want to change to the new name to avoid a relatively pointless redirect. --- Documentation/usage.tely | 4 +- .../{converters.itely => external.itely} | 271 +++++++++++++++++- Documentation/usage/lilypond-book.itely | 60 +--- Documentation/usage/running.itely | 180 ------------ 4 files changed, 270 insertions(+), 245 deletions(-) rename Documentation/usage/{converters.itely => external.itely} (53%) diff --git a/Documentation/usage.tely b/Documentation/usage.tely index 0ce6002b62..9d0297b43d 100644 --- a/Documentation/usage.tely +++ b/Documentation/usage.tely @@ -49,7 +49,7 @@ Copyright @copyright{} 1999--2009 by the authors. * 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. +* External programs:: Mixing LilyPond and other programs. * Suggestions for writing files:: Best practices and effective bug-fixing. Appendices @@ -68,7 +68,7 @@ Appendices @include usage/running.itely @include usage/updating.itely @include usage/lilypond-book.itely -@include usage/converters.itely +@include usage/external.itely @include usage/suggestions.itely @include fdl.itexi diff --git a/Documentation/usage/converters.itely b/Documentation/usage/external.itely similarity index 53% rename from Documentation/usage/converters.itely rename to Documentation/usage/external.itely index 8dab496eb4..53274b4f5e 100644 --- a/Documentation/usage/converters.itely +++ b/Documentation/usage/external.itely @@ -9,8 +9,202 @@ @c \version "2.12.0" +@node External programs +@chapter External programs + +FIXME: blah blah + + +@menu +* Point and click:: +* Text editor support:: +* Converting from other formats:: +* LilyPond output in other programs:: +@end menu + + +@node Point and click +@section Point and click + +@cindex point and click + +Point and click lets you find notes in the input by clicking on them +in the PDF viewer. This makes it easier to find input that causes +some error in the sheet music. + +When this functionality is active, LilyPond adds hyperlinks to the PDF +file. These hyperlinks are sent to the web-browser, which opens a +text-editor with the cursor in the right place. + +To make this chain work, you should configure your PDF viewer to +follow hyperlinks using the @file{lilypond-invoke-editor} script +supplied with LilyPond. + +For Xpdf on UNIX, the following should be present in +@file{xpdfrc}@footnote{On UNIX, this file is found either in +@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} + +@example +urlCommand "lilypond-invoke-editor %s" +@end example + +The program @file{lilypond-invoke-editor} is a small helper +program. It will invoke an editor for the special @code{textedit} +URIs, and run a web browser for others. It tests the environment +variable @code{EDITOR} for the following patterns, + +@table @code +@item emacs + this will invoke +@example +emacsclient --no-wait +@var{line}:@var{column} @var{file} +@end example +@item gvim + this will invoke +@example +gvim --remote +:@var{line}:norm@var{column} @var{file} +@end example + +@item nedit +this will invoke +@example + nc -noask +@var{line} @var{file}' +@end example +@end table + +The environment variable @code{LYEDITOR} is used to override this. It +contains the command line to start the editor, where @code{%(file)s}, +@code{%(column)s}, @code{%(line)s} is replaced with the file, column +and line respectively. The setting + +@example +emacsclient --no-wait +%(line)s:%(column)s %(file)s +@end example + +@noindent +for @code{LYEDITOR} is equivalent to the standard emacsclient +invocation. + + +@cindex file size, output + +The point and click links enlarge the output files significantly. For +reducing the size of PDF and PS files, point and click may be switched +off by issuing + +@example +\pointAndClickOff +@end example + +@noindent +in a @file{.ly} file. Point and click may be explicitly enabled with + +@example +\pointAndClickOn +@end example + +Alternately, you may disable point and click with a command-line +option: + +@example +lilypond -dno-point-and-click file.ly +@end example + +@warning{You should always turn off point and click in any LilyPond +files to be distributed to avoid including path information about +your computer in the .pdf file, which can pose a security risk.} +@node Text editor support +@section Text editor support + +@cindex editors +@cindex vim +@cindex emacs +@cindex modes, editor +@cindex syntax coloring +@cindex coloring, syntax + +There is support for different text editors for LilyPond. + +@menu +* Emacs mode:: +* Vim mode:: +* Other editors:: +@end menu + +@node Emacs mode +@unnumberedsubsec Emacs mode + +Emacs has a @file{lilypond-mode}, which provides keyword +autocompletion, indentation, LilyPond specific parenthesis matching +and syntax coloring, handy compile short-cuts and reading LilyPond +manuals using Info. If @file{lilypond-mode} is not installed on your +platform, see below. + +An Emacs mode for entering music and running LilyPond is contained in +the source archive in the @file{elisp} directory. Do @command{make +install} to install it to @var{elispdir}. The file @file{lilypond-init.el} +should be placed to @var{load-path}@file{/site-start.d/} or appended +to your @file{~/.emacs} or @file{~/.emacs.el}. + +As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to +your @var{load-path} by appending the following line (as modified) to your +@file{~/.emacs} + +@c any reason we do not advise: (push "~/site-lisp" load-path) +@example +(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path)) +@end example + + +@node Vim mode +@unnumberedsubsec Vim mode + +For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, +along with syntax coloring tools. A Vim mode for entering music and +running LilyPond is contained in the source archive in @code{$VIM} +directory. + +The LilyPond file type is detected if the file +@file{~/.vim/filetype.vim} has the following content + +@example +if exists("did_load_filetypes") + finish +endif +augroup filetypedetect + au! BufNewFile,BufRead *.ly,*.ily setf lilypond +augroup END +@end example + +Please include this path by appending the following line to your +@file{~/.vimrc} + +@example +set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/ +@end example + +@noindent +where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not +installed in @file{/usr/local/}, then change this path accordingly. +The path may differ significantly. In Fedora the path leads to the +current version of Vim instead of Lilypond: + +@example +set runtimepath+=/usr/share/vim/vim72/ +@end example + + +@node Other editors +@unnumberedsubsec Other editors + +Other editors (both text and graphical) support LilyPond, but +their special configuration files are not distributed with +LilyPond. Consult their documentation for more information. Such +editors are listed in @rweb{Alternate editors}. + + @node Converting from other formats -@chapter Converting from other formats +@section Converting from other formats Music can be entered also by importing it from other formats. This chapter documents the tools included in the distribution to do so. @@ -41,7 +235,7 @@ bug reports will almost certainly not be resolved. @node Invoking midi2ly -@section Invoking @command{midi2ly} +@subsection Invoking @command{midi2ly} @cindex MIDI @@ -128,7 +322,7 @@ to a single duration and add phrase markings or pedal indicators. @node Invoking musicxml2ly -@section Invoking @code{musicxml2ly} +@subsection Invoking @code{musicxml2ly} @cindex MusicXML @@ -196,7 +390,7 @@ input file is a zip-compressed MusicXML file. @node Invoking abc2ly -@section Invoking @code{abc2ly} +@subsection Invoking @code{abc2ly} @warning{This program is not supported, and may be remove from future versions of LilyPond.} @@ -264,7 +458,7 @@ ABC synchronizes words and notes at the beginning of a line; @node Invoking etf2ly -@section Invoking @command{etf2ly} +@subsection Invoking @command{etf2ly} @warning{This program is not supported, and may be remove from future versions of LilyPond.} @@ -307,7 +501,7 @@ confuse @command{etf2ly}. Sequences of grace notes are ended improperly. @node Other formats -@section Other formats +@subsection Other formats @cindex External programs, generating LilyPond files @@ -315,3 +509,68 @@ LilyPond itself does not come with support for any other formats, but some external tools can also generate LilyPond files. These are listed in @rweb{Alternate editors}. + + +@node LilyPond output in other programs +@section LilyPond output in other programs + +This section shows methods to integrate text and music, different than +the automated method with @command{lilypond-book}. + +@menu +* Many quotes from a large score:: +* Inserting LilyPond output into OpenOffice.org:: +* Inserting LilyPond output into other programs:: +@end menu + +@node Many quotes from a large score +@unnumberedsubsec Many quotes from a large score + +If you need to quote many fragments from a large score, you can also use +the clip systems feature, see @ruser{Extracting fragments of music}. + + +@node Inserting LilyPond output into OpenOffice.org +@unnumberedsubsec Inserting LilyPond output into OpenOffice.org + +@cindex OpenOffice.org + +LilyPond notation can be added to OpenOffice.org with +@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}. + + +@node Inserting LilyPond output into other programs +@unnumberedsubsec Inserting LilyPond output into other programs + +To insert LilyPond output in other programs, use @code{lilypond} +instead of @code{lilypond-book}. Each example must be created +individually and added to the document; consult the documentation for +that program. Most programs will be able to insert LilyPond output in +@file{PNG}, @file{EPS}, or @file{PDF} formats. + +To reduce the white space around your LilyPond score, use +the following options + +@example +\paper@{ + indent=0\mm + line-width=120\mm + oddFooterMarkup=##f + oddHeaderMarkup=##f + bookTitleMarkup = ##f + scoreTitleMarkup = ##f +@} + +@{ c1 @} +@end example + +To produce a useful @file{EPS} file, use + +@example +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly + +@file{PNG}: +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly +@end example + + diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely index d184b1705c..4e2aa4c5cd 100644 --- a/Documentation/usage/lilypond-book.itely +++ b/Documentation/usage/lilypond-book.itely @@ -1107,62 +1107,8 @@ unterst__tzt werden. @node Alternate methods of mixing text and music @section Alternative methods of mixing text and music -This section shows methods to integrate text and music, different than -the automated method with @command{lilypond-book}. +Other means of mixing text and music (without +@command{lilypond-book}) are discussed in +@ref{LilyPond output in other programs}. -@menu -* Many quotes from a large score:: -* Inserting LilyPond output into OpenOffice.org:: -* Inserting LilyPond output into other programs:: -@end menu - -@node Many quotes from a large score -@unnumberedsubsec Many quotes from a large score - -If you need to quote many fragments from a large score, you can also use -the clip systems feature, see @ruser{Extracting fragments of music}. - - -@node Inserting LilyPond output into OpenOffice.org -@unnumberedsubsec Inserting LilyPond output into OpenOffice.org - -@cindex OpenOffice.org - -LilyPond notation can be added to OpenOffice.org with -@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}. - - -@node Inserting LilyPond output into other programs -@unnumberedsubsec Inserting LilyPond output into other programs - -To insert LilyPond output in other programs, use @code{lilypond} -instead of @code{lilypond-book}. Each example must be created -individually and added to the document; consult the documentation for -that program. Most programs will be able to insert LilyPond output in -@file{PNG}, @file{EPS}, or @file{PDF} formats. - -To reduce the white space around your LilyPond score, use -the following options - -@example -\paper@{ - indent=0\mm - line-width=120\mm - oddFooterMarkup=##f - oddHeaderMarkup=##f - bookTitleMarkup = ##f - scoreTitleMarkup = ##f -@} - -@{ c1 @} -@end example - -To produce a useful @file{EPS} file, use - -@example -lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly - -@file{PNG}: -lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly -@end example diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 1f79d36536..174aa6310b 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -20,8 +20,6 @@ This chapter details the technicalities of running LilyPond. * Command-line usage:: * Error messages:: * Common errors:: -* Point and click:: -* Text editor support:: @end menu @@ -637,182 +635,4 @@ an input file contains a non-ASCII character and was not saved in UTF-8 encoding. For details, see @ruser{Text encoding}. -@node Point and click -@section Point and click - -@cindex point and click - -Point and click lets you find notes in the input by clicking on them -in the PDF viewer. This makes it easier to find input that causes -some error in the sheet music. - -When this functionality is active, LilyPond adds hyperlinks to the PDF -file. These hyperlinks are sent to the web-browser, which opens a -text-editor with the cursor in the right place. - -To make this chain work, you should configure your PDF viewer to -follow hyperlinks using the @file{lilypond-invoke-editor} script -supplied with LilyPond. - -For Xpdf on UNIX, the following should be present in -@file{xpdfrc}@footnote{On UNIX, this file is found either in -@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} - -@example -urlCommand "lilypond-invoke-editor %s" -@end example - -The program @file{lilypond-invoke-editor} is a small helper -program. It will invoke an editor for the special @code{textedit} -URIs, and run a web browser for others. It tests the environment -variable @code{EDITOR} for the following patterns, - -@table @code -@item emacs - this will invoke -@example -emacsclient --no-wait +@var{line}:@var{column} @var{file} -@end example -@item gvim - this will invoke -@example -gvim --remote +:@var{line}:norm@var{column} @var{file} -@end example - -@item nedit -this will invoke -@example - nc -noask +@var{line} @var{file}' -@end example -@end table - -The environment variable @code{LYEDITOR} is used to override this. It -contains the command line to start the editor, where @code{%(file)s}, -@code{%(column)s}, @code{%(line)s} is replaced with the file, column -and line respectively. The setting - -@example -emacsclient --no-wait +%(line)s:%(column)s %(file)s -@end example - -@noindent -for @code{LYEDITOR} is equivalent to the standard emacsclient -invocation. - - -@cindex file size, output - -The point and click links enlarge the output files significantly. For -reducing the size of PDF and PS files, point and click may be switched -off by issuing - -@example -\pointAndClickOff -@end example - -@noindent -in a @file{.ly} file. Point and click may be explicitly enabled with - -@example -\pointAndClickOn -@end example - -Alternately, you may disable point and click with a command-line -option: - -@example -lilypond -dno-point-and-click file.ly -@end example - -@warning{You should always turn off point and click in any LilyPond -files to be distributed to avoid including path information about -your computer in the .pdf file, which can pose a security risk.} -@node Text editor support -@section Text editor support - -@cindex editors -@cindex vim -@cindex emacs -@cindex modes, editor -@cindex syntax coloring -@cindex coloring, syntax - -There is support for different text editors for LilyPond. - -@menu -* Emacs mode:: -* Vim mode:: -* Other editors:: -@end menu - -@node Emacs mode -@unnumberedsubsec Emacs mode - -Emacs has a @file{lilypond-mode}, which provides keyword -autocompletion, indentation, LilyPond specific parenthesis matching -and syntax coloring, handy compile short-cuts and reading LilyPond -manuals using Info. If @file{lilypond-mode} is not installed on your -platform, see below. - -An Emacs mode for entering music and running LilyPond is contained in -the source archive in the @file{elisp} directory. Do @command{make -install} to install it to @var{elispdir}. The file @file{lilypond-init.el} -should be placed to @var{load-path}@file{/site-start.d/} or appended -to your @file{~/.emacs} or @file{~/.emacs.el}. - -As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to -your @var{load-path} by appending the following line (as modified) to your -@file{~/.emacs} - -@c any reason we do not advise: (push "~/site-lisp" load-path) -@example -(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path)) -@end example - - -@node Vim mode -@unnumberedsubsec Vim mode - -For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, -along with syntax coloring tools. A Vim mode for entering music and -running LilyPond is contained in the source archive in @code{$VIM} -directory. - -The LilyPond file type is detected if the file -@file{~/.vim/filetype.vim} has the following content - -@example -if exists("did_load_filetypes") - finish -endif -augroup filetypedetect - au! BufNewFile,BufRead *.ly,*.ily setf lilypond -augroup END -@end example - -Please include this path by appending the following line to your -@file{~/.vimrc} - -@example -set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/ -@end example - -@noindent -where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not -installed in @file{/usr/local/}, then change this path accordingly. -The path may differ significantly. In Fedora the path leads to the -current version of Vim instead of Lilypond: - -@example -set runtimepath+=/usr/share/vim/vim72/ -@end example - - -@node Other editors -@unnumberedsubsec Other editors - -Other editors (both text and graphical) support LilyPond, but -their special configuration files are not distributed with -LilyPond. Consult their documentation for more information. Such -editors are listed in @rweb{Alternate editors}. -- 2.39.5