From: Graham Percival Date: Sat, 5 Sep 2009 03:57:13 +0000 (+0100) Subject: Doc: AU reorg. X-Git-Tag: release/2.13.4-1~75 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=21aaea48f871f291ca52ee65a6c918e706715ee7;p=lilypond.git Doc: AU reorg. --- diff --git a/Documentation/application/running.itely b/Documentation/application/running.itely index 966e226b62..fa195aec59 100644 --- a/Documentation/application/running.itely +++ b/Documentation/application/running.itely @@ -19,6 +19,8 @@ This chapter details the technicalities of running LilyPond. * Normal usage:: * Command-line usage:: * Error messages:: +* Point and click:: +* Text editor support:: @end menu @@ -487,3 +489,219 @@ above the indicated position. More information about errors is given in @ref{Common errors}. +@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 vim + this will invoke +@example +gvim --remote +:@var{line}:norm@var{char} @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 from different text editors for LilyPond. + +@menu +* Emacs mode:: +* Vim mode:: +* jEdit:: +* TexShop:: +* TextMate:: +* LilyKDE:: +@end menu + +@node Emacs mode +@subsection 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 +@subsection 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. + + +@node jEdit +@subsection jEdit + +Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} +text editor, LilyPondTool is the most feature-rich text-based tool for +editing LilyPond scores. Its features include a Document Wizard with +lyrics support to set up documents easier, and embedded PDF viewer with +advanced point-and-click support. For screenshots, demos and +installation instructions, visit +@uref{http://lilypondtool@/.organum@/.hu} + + +@node TexShop +@subsection TexShop + +The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop} +editor for MacOS@tie{}X can be extended to run LilyPond, lilypond-book and +convert-ly from within the editor, using the extensions available at +@uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}. + + +@node TextMate +@subsection TextMate + +There is a LilyPond bundle for TextMate. It may be installed by running + +@example +mkdir -p /Library/Application\ Support/TextMate/Bundles +cd /Library/Application\ Support/TextMate/Bundles +svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/ +@end example + + +@node LilyKDE +@subsection LilyKDE + +@uref{http://lilykde.googlecode.com/,LilyKDE} is a plugin for KDE's +text editor @uref{http://kate-editor.org/,Kate}. It has a powerful Score +Wizard to quickly setup a LilyPond document and an embedded PDF viewer. + +LilyKDE can use @uref{http://www.volny.cz/smilauer/rumor/,Rumor}, +so music can entered by playing on a MIDI keyboard. + +Other features are lyric hyphenation and running LilyPond on multiple files +at once from within the KDE file manager. + + + diff --git a/Documentation/application/suggestions.itely b/Documentation/application/suggestions.itely index 9bf3e2add5..bd58b7c687 100644 --- a/Documentation/application/suggestions.itely +++ b/Documentation/application/suggestions.itely @@ -45,8 +45,6 @@ structured in order to be easier (or harder) to update. * Typesetting existing music:: * Large projects:: * When things don't work:: -* Point and click:: -* Text editor support:: * Make and Makefiles:: @end menu @@ -401,221 +399,6 @@ Another very useful debugging technique is constructing @rgeneral{Tiny examples}. -@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 vim - this will invoke -@example -gvim --remote +:@var{line}:norm@var{char} @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 from different text editors for LilyPond. - -@menu -* Emacs mode:: -* Vim mode:: -* jEdit:: -* TexShop:: -* TextMate:: -* LilyKDE:: -@end menu - -@node Emacs mode -@subsection 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 -@subsection 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. - - -@node jEdit -@subsection jEdit - -Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} -text editor, LilyPondTool is the most feature-rich text-based tool for -editing LilyPond scores. Its features include a Document Wizard with -lyrics support to set up documents easier, and embedded PDF viewer with -advanced point-and-click support. For screenshots, demos and -installation instructions, visit -@uref{http://lilypondtool@/.organum@/.hu} - - -@node TexShop -@subsection TexShop - -The @uref{http://@/www@/.uoregon@/.edu/~koch/texshop/index@/.html,TexShop} -editor for MacOS@tie{}X can be extended to run LilyPond, lilypond-book and -convert-ly from within the editor, using the extensions available at -@uref{http://@/www@/.dimi@/.uniud@/.it/vitacolo/freesoftware@/.html}. - - -@node TextMate -@subsection TextMate - -There is a LilyPond bundle for TextMate. It may be installed by running - -@example -mkdir -p /Library/Application\ Support/TextMate/Bundles -cd /Library/Application\ Support/TextMate/Bundles -svn co http://macromates.com/svn/Bundles/trunk/Bundles/Lilypond.tmbundle/ -@end example - - -@node LilyKDE -@subsection LilyKDE - -@uref{http://lilykde.googlecode.com/,LilyKDE} is a plugin for KDE's -text editor @uref{http://kate-editor.org/,Kate}. It has a powerful Score -Wizard to quickly setup a LilyPond document and an embedded PDF viewer. - -LilyKDE can use @uref{http://www.volny.cz/smilauer/rumor/,Rumor}, -so music can entered by playing on a MIDI keyboard. - -Other features are lyric hyphenation and running LilyPond on multiple files -at once from within the KDE file manager. - - @node Make and Makefiles @section Make and Makefiles