X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=1668953b1ffad9690aa3e7600abf05b55de61c89;hb=7999d5e8591881a10a4a47a67b2b721df1731e7e;hp=53274b4f5e8f2f76f50ad5ca2e22e00d88d58b5c;hpb=06ba37b9fc842694c68d68fe762ef1ce60bb3fda;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 53274b4f5e..1668953b1f 100644 --- a/Documentation/usage/external.itely +++ b/Documentation/usage/external.itely @@ -4,28 +4,40 @@ 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. + version that you are working on. For details, see the Contributors' + Guide, node Updating translation committishes.. @end ignore -@c \version "2.12.0" +@c \version "2.14.0" @node External programs @chapter External programs -FIXME: blah blah - +LilyPond can interact with other programs in various ways. @menu * Point and click:: * Text editor support:: * Converting from other formats:: * LilyPond output in other programs:: +* Independent includes:: @end menu @node Point and click @section Point and click +Point and click adds links to pdf documents for certain music +elements. + +@menu +* Enabling point and click:: +* Selective point-and-click:: +@end menu + +@node Enabling point and click +@unnumberedsubsec Enabling point and click + @cindex point and click Point and click lets you find notes in the input by clicking on them @@ -41,8 +53,8 @@ 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.} +@file{xpdfrc}. On UNIX, this file is found either in +@file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}. @example urlCommand "lilypond-invoke-editor %s" @@ -113,6 +125,83 @@ lilypond -dno-point-and-click file.ly @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 Selective point-and-click +@unnumberedsubsec Selective point-and-click + +For some interactive applications, it may be desirable to only +include certain point-and-click items. For example, if somebody +wanted to create an application which played audio or video +starting from a particular note, it would be awkward if clicking +on the note produced the point-and-click location for an +accidental or slur which occurred over that note. + +This may be controlled by indicating which events to include: + +@itemize +@item +Hard-coded in the @file{.ly} file: + +@example +\pointAndClickTypes #'note-event +\relative c' @{ + c2\f( f) +@} +@end example + +or + +@example +#(ly:set-option 'point-and-click 'note-event) +\relative c' @{ + c2\f( f) +@} +@end example + +@item +Command-line: + +@example +lilypond -dpoint-and-click=note-event example.ly +@end example + +@end itemize + +Multiple events can be included: + +@itemize +@item +Hard-coded in the @file{.ly} file: + +@example +\pointAndClickTypes #'(note-event dynamic-event) +\relative c' @{ + c2\f( f) +@} +@end example + +or + +@example +#(ly:set-option 'point-and-click '(note-event dynamic-event)) +\relative c' @{ + c2\f( f) +@} +@end example + +@item +Command-line: + +@smallexample +lilypond \ + -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \ + example.ly +@end smallexample + + +@end itemize + + @node Text editor support @section Text editor support @@ -159,39 +248,21 @@ your @var{load-path} by appending the following line (as modified) to your @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} +For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent +mode, and syntax-highlighting mode are available to use with +LilyPond. To enable all of these features, create (or modify) +your @file{$HOME/.vimrc} to contain these three lines, in order: @example -set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/ +filetype off +set runtimepath+=/usr/local/share/lilypond/current/vim/ +filetype on @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 +If LilyPond is not installed in the @file{/usr/local/} directory, +change the path appropriately. This topic is discussed in +@rlearning{Other sources of information}. @node Other editors @@ -200,7 +271,7 @@ set runtimepath+=/usr/share/vim/vim72/ 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}. +editors are listed in @rweb{Easier editing}. @node Converting from other formats @@ -256,7 +327,7 @@ for pitches, durations are only written when necessary. It is possible to record a MIDI file using a digital keyboard, and then convert it to @file{.ly}. However, human players are not rhythmically exact enough to make a MIDI to LY conversion trivial. -When invoked with quantizing (@code{-s} and @code{-d} options) +When invoked with quantizing (@option{-s} and @option{-d} options) @command{midi2ly} tries to compensate for these timing errors, but is not very good at this. It is therefore not recommended to use @command{midi2ly} for human-generated midi files. @@ -330,7 +401,7 @@ to a single duration and add phrase markings or pedal indicators. for representing music notation. @command{musicxml2ly} extracts the notes, articulations, score structure, -lyrics, etc. from part-wise MusicXML files, and writes them to a .ly +lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly} file. It is invoked from the command-line. @@ -356,8 +427,11 @@ convert pitches in absolute mode. print usage and option summary. @item -l, --language=LANG -use a different language file 'LANG.ly' and corresponding pitch names, -e.g. 'deutsch' for deutsch.ly and German note names. +use LANG for pitch names, e.g. 'deutsch' for note names in German. + +@item --loglevel=@var{loglevel} +Set the output verbosity to @var{loglevel}. Possible values are @code{NONE}, +@code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}. @item --lxml use the lxml.etree Python package for XML-parsing; uses less memory and cpu time. @@ -507,7 +581,7 @@ confuse @command{etf2ly}. Sequences of grace notes are ended improperly. 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}. +are listed in @rweb{Easier editing}. @@ -564,13 +638,62 @@ the following options @{ c1 @} @end example -To produce a useful @file{EPS} file, use +To produce useful image files: @example -lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly +EPS + +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly + +PNG -@file{PNG}: lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly + +A transparent PNG + +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \ + -dpixmap-format=pngalpha --png myfile.ly @end example +@node Independent includes +@section Independent @code{include}s + +Some people have written large (and useful!) code that can be +shared between projects. This code might eventually make its way +into LilyPond itself, but until that happens, you must download +and @code{\include} them manually. + + +@menu +* MIDI articulation:: +@end menu + + +@node MIDI articulation +@subsection MIDI articulation + +LilyPond can be used to produce MIDI output, for +@qq{proof-hearing} what has been written. However, only dynamics, +explicit tempo markings, and the notes and durations themselves +are produced in the output. + +The @emph{articulate} project is one attempt to get more of the +information in the score into he MIDI. It works by shortening +notes not under slurs, to @q{articulate} the notes. The amount of +shortening depends on any articulation markings attached to a +note: staccato halves the note value, tenuto gives a note its full +duration, and so on. The script also realises trills and turns, +and could be extended to expand other ornaments such as mordents. + +@example +@uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate} +@end example + +@knownissues + +Its main limitation is that it can only affect things it knows +about: anything that is merely textual markup (instead of a note +property) is still ignored. + +