From: fred Date: Wed, 27 Mar 2002 00:35:21 +0000 (+0000) Subject: lilypond-1.3.122 X-Git-Tag: release/1.5.59~1003 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=7503d4e3f41b82cb047f4acc09686afabf43fe90;p=lilypond.git lilypond-1.3.122 --- diff --git a/Documentation/user/bugs.itexi b/Documentation/user/bugs.itexi index d9ba1abeeb..e6500cc39e 100644 --- a/Documentation/user/bugs.itexi +++ b/Documentation/user/bugs.itexi @@ -1,5 +1,7 @@ -@node Reporting Bugs, , , Top -@section Bug reports +@node Reporting Bugs, , , top +@chapter Bug reports +@cindex bugs +@cindex reporting bugs LilyPond development moves quickly, so if you have a problem, it is wise to check if it has been fixed in a newer release. If you think diff --git a/Documentation/user/convert-ly.itexi b/Documentation/user/convert-ly.itexi index 5c413c6227..e1658dbbc6 100644 --- a/Documentation/user/convert-ly.itexi +++ b/Documentation/user/convert-ly.itexi @@ -1,4 +1,5 @@ -@node convert-ly, , ,Top + +@node convert-ly, , , Top @chapter convert-ly @code{convert-ly} sequentially applies different lilypond-conversions to upgrade a Lilypond input file. It uses diff --git a/Documentation/user/development.itexi b/Documentation/user/development.itexi index fa6b0dfb17..56a37a4d9c 100644 --- a/Documentation/user/development.itexi +++ b/Documentation/user/development.itexi @@ -1,8 +1,7 @@ -@node Internals, , , top +@node Internals, , , Top @menu * Conversion stages:: Lilypond is a multi-pass program. - * Grobs:: Graphical object * Engraver:: * Music_iterator:: @@ -10,13 +9,12 @@ * Molecules:: Molecules are stand-alone descriptions of output @end menu - -@node Conversion stages, , , Internals +@node Conversion stages +@section Conversion stages When translating the input to notation, there are number of distinct phases. We list them here: - @table @samp @item Parsing: @@ -25,6 +23,7 @@ The .ly file is read, and converted to a list of @code{Scores}, which each contain @code{Music} and paper/midi-definitions. @item Interpreting music +@cindex interpreting music All music events are "read" in the same order as they would be played (or read from paper). At every step of the interpretation, musical @@ -35,11 +34,15 @@ which use them to build grobs (or MIDI objects, for MIDI output). @item Prebreaking +@cindex prebreaking + At places where line breaks may occur, clefs and bars are prepared for a possible line break. @item Preprocessing +@cindex preprocessing + In this stage, all information that is needed to determine line breaking is computed. @@ -60,7 +63,7 @@ are output, line by line. @end table -@node Grobs, , , Internals +@node Grobs @section Grobs This section is about Grobs (short for Graphical Objects), which are @@ -90,7 +93,8 @@ how grobs work. * Pointer substitution:: @end menu -@node What is a grob?, , , Grobs +@node What is a grob? +@subsection What is a grob? In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the @@ -146,7 +150,8 @@ dimensions, line breaks, etc. are calculated. Finally, the printing description in the form of Molecules (@ref{Molecules}) is extracted from the network. These are then dumped into the output file -@node Callbacks, , , Grobs +@node Callbacks +@subsection Callbacks Offsets of grobs are relative to a parent reference point. Most positions are not known when an object is created, so these are @@ -196,7 +201,8 @@ means: "empty in this direction". If you fill in a pair, that pair hard-codes the extent in that coordinate. -@node Setting grob properties, , , Grobs +@node Setting grob properties +@subsection Setting grob properties Grob properties are stored as GUILE association lists, with symbols as keys. From C++, element properties can be accessed using the functions @@ -281,7 +287,7 @@ This shifts all elements that have a @code{text} property one staff space to the left. This mechanism is rather clumsy to use, but it allows you tweak any setting of any grob. -@node Items and Spanners, , , Grobs +@node Items and Spanners @unnumberedsubsec Items and Spanners Grobs can also be distinguished in their role in the horizontal spacing. @@ -308,7 +314,7 @@ the outcome of the visibility-lambda. This is a function taking a direction (-1, 0 or 1) and returns a cons of booleans, signifying wether this grob should be transparent and invisible. -@node Pointer substitution, , , Grobs +@node Pointer substitution @unnumberedsubsec Pointer substitution @@ -318,13 +324,21 @@ complications. When a spanner crosses a line-break, then the spanner is the grob is made. A substitution process redirects all grob-reference so that spanner grob will only reference other grobs in the same line. -@node Engraver, , , Internals +@node Engraver +@section Engraver -@node Music_iterator, , , Internals +@node Music_iterator +@section Music_iterator -@node Music, , , Internals +@node Music +@section Music -@node Molecules, , , Internals +@node Molecules +@section Molecules + +@cindex Molecule +@cindex Atom +@cindex Output description The objective of any typesetting system is to put ink on paper in the right places. For LilyPond, this final stage is left to the TeX and the @@ -346,7 +360,8 @@ dimension information (how large is this glyph ?) with what-to-print-where. Conceptually, Molecules can be constructed from Scheme code, by -translating a Molecule and by combining two molecules. In BNF notation: +translating a Molecule and by combining two molecules. In BNF +notation: @example Molecule = COMBINE Molecule Molecule @@ -355,21 +370,26 @@ translating a Molecule and by combining two molecules. In BNF notation: ; @end example +If you are interested in seeing how this information is stored, you +can run with the @code{-f scm} option. The scheme expressions are then +dumped onto the output file. + (refer to the C++ code for more details). All visible, -ie. non-transparent, grobs have a callback to create a Molecule. The +ie. non-transparant, grobs have a callback to create a Molecule. The name of the property is @code{molecule-callback}, and its value should be a Scheme function taking one argument (the grob) and returning a Molecule. -@node Development, , , top +@node Development, , , top @chapter Development @menu * CodingStyle:: * Making patches:: * Localisation:: +* Helping with development:: @end menu @node CodingStyle, , , Development @@ -602,7 +622,7 @@ files, doing a release. Use them. @node Making patches, , , Development - +@section Making patches @unnumberedsec Track and distribute your code changes @@ -702,10 +722,7 @@ and don't forget to make automatically generated files: @end example @node Localisation, , , Development - -@chapter Localisation - User messages in LilyPond - -@section Introduction +@section Localisation - User messages in LilyPond This document provides some guidelines for uniformising user messages. In the absence of other standards, we'll be using these rules when coding @@ -715,7 +732,7 @@ guidelines in the future. Not-preferred messages are marked with @code{+}. By convention, agrammatical examples are marked with @code{*}. -@section Guidelines +@subsection Guidelines @itemize @bullet @@ -865,3 +882,81 @@ I guess we'd prefer something like (2) or (3). Please don't run make po/po-update with GNU gettext < 0.10.35 @end itemize + +@node Helping with development, , , Development + +@chapter Getting involved + +If you want to help developing LilyPond your efforts are appreciated. +You can help LilyPond in several ways. Not all tasks requiring +programming or understanding the full source code. + +Please don't expect us to give you instructions on what you should +do. We're just a bunch of simple hackers, and we're absolutely +incompetent about management, design in advance, delegating work. +Some people write to us "I want to help, what should I do?", but we +never know what to answer them. + +If you want to hack, just start hacking. You can send us the result as +a patch, and we'll gladly incorporate it. + +If you need some hints on where to get started: there are a number of +specific areas where you could do work. + +@unnumberedsubsec Users + +Mutopia needs your help. The mutopia project is a collection of public +domain sheet music. You can help the project by entering music (either +by hand, or by converting from scans or MIDI) and submitting it. Point +your browser to the @uref{http://sca.uwaterloo.ca/Mutopia, Mutopia +webpage}. + +@unnumberedsubsec Writers + +The documentation of LilyPond and related utilities needs a lot of +work. The documentation is written in +@uref{http://www.gnu.org/software/texinfo,texinfo}. The documentation of +LilyPond is sorely lacking in terms of completeness, depth and +organisation. + +Write if you know how to write english documentation in texinfo, and +know about music and music notation. You must also know how to use +LilyPond (or be prepared to learn using it). The task is not especially +hard, but it is a lot of work, and you must be familiar with LilyPond. + +@unnumberedsubsec Translators + +LilyPond is completely ready for internationalized messages, but there +are only a few translations so far (dutch, italian, german, japanese, +french, russian). Translation involves writing a .po file, which is +relatively easy, and does not even require running LilyPond. + +@unnumberedsubsec Hackers + +There are lots of possibilities of improving the program itself. There +are both small projects and big ones. Most of them are listed in our +TODO file, listed on the homepage of Jan and +@uref{http://www.cs.uu.nl/~hanwen/lily-devel,Han-Wen}. Modifying +LilyPond almost always requires patches to the C++ part. + +There are also numerous other interesting projects that are more or less +related to LilyPond + +@itemize @bullet +@item Writing convertors, eg. from NIFF and MIDI (we tried writing one with +limited success: midi2ly, included with lilypond.) + +We found that writing them in Python is the easiest. + +@item Writing a GUI frontend to +LilyPond. At the moment @uref{denemo,denemo.sourceforge.net} is the most +advanced. + +@item Helping write @uref{http://solfege.sourceforge.net/,solfege +tools} + +@item Helping @uref{primrose.sourceforge.net,primrose}, a tool for +scanning sheet music. +@end itemize + + diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 13a40742be..2f24bdaefe 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -1,19 +1,24 @@ +@node Invoking LilyPond, , , top -@node Invoking LilyPond, , , Top @chapter Invoking LilyPond @cindex Invoking LilyPond +@cindex command line options +@cindex options, command line +@cindex switches @example - @strong{lilypond} [OPTION]... [MUDELA-FILE]... + lilypond [OPTION]... [MUDELA-FILE]... @end example -@section Options +@unnumberedsec Lilypond Command Options @table @samp @item -f,--format= Output format for sheet music. Choices are tex (for @TeX{} - output), ps (for PostScript) and scm (for GUILE) + output), ps (for PostScript) and scm (for a direct Scheme + dump) + @item -h,--help Show a summary of usage. @item --include, -I=DIRECTORY @@ -57,13 +62,13 @@ When invoked with a filename that has no extension, LilyPond will try adding `@file{.ly}' as an extension first. When LilyPond processes @file{filename.ly} it will produce -@file{filename.tex} as output (or @file{filename.ps} for -PostScript output). If @file{filename.ly} contains more than one -@code{\score} block, then LilyPond will output the rest 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 defaults settings from within Scheme .} +@file{filename.tex} as output (or @file{filename.ps} for PostScript +output). If @file{filename.ly} contains more than one @code{\score} +block, then LilyPond will output the rest 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 default +settings from within Scheme .} @section Environment variables diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index e2d9cfbd08..4b47b0a6e5 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -85,9 +85,12 @@ than the names being similar :-)" @end ignore -@node Top, , , (dir) -@chapter GNU LilyPond --- The music typesetter +@ifnottex +@node Top +@top +@end ifnottex +@chapter GNU LilyPond --- The music typesetter LilyPond produces sheet music from input files. This document describes how to use LilyPond. @@ -108,37 +111,35 @@ this and other documentation. @c Move to Reference Manual? * Internals:(lilypond-internals). Auto generated detailed documentation. * convert-ly:: Upgrading input files. -* Internals:: -* Development:: Some hints on developing for LilyPond. +* Internals:: How it all works. +* Development:: On developing code for LilyPond. * Index:: Unified index. @end menu @contents @macro keyindex {word} -@cindex \word\ - +@cindex \\@code{\word\} @end macro @macro indexcode {word} -@cindex \word\ - +@cindex @code{\word\} @end macro @mbinclude tutorial.itely -@include invoking.itexi +@mbinclude invoking.itexi -@include bugs.itexi +@mbinclude bugs.itexi @mbinclude refman.itely -@include convert-ly.itexi +@mbinclude convert-ly.itexi -@include development.itexi +@mbinclude development.itexi -@node Index, , , Top +@node Index, , , top @unnumbered Index @printindex cp