From efa38c97b040f3ef74d692ed7e375b7d6c7e7949 Mon Sep 17 00:00:00 2001 From: fred Date: Tue, 26 Mar 2002 22:25:25 +0000 Subject: [PATCH] lilypond-1.2.6 --- Documentation/CodingStyle.texi | 401 +++++++++++++++++++++++++ Documentation/MANIFESTO.texi | 114 +++++++ Documentation/disclaimer-w32.texi | 19 ++ Documentation/gnu-music.texi | 112 +++++++ Documentation/internals.texi | 326 ++++++++++++++++++++ Documentation/mail.texi | 56 ++++ debian/control | 9 +- stepmake/configure | 314 +------------------ stepmake/configure.in | 3 - stepmake/stepmake/texinfo-targets.make | 2 + 10 files changed, 1035 insertions(+), 321 deletions(-) create mode 100644 Documentation/CodingStyle.texi create mode 100644 Documentation/MANIFESTO.texi create mode 100644 Documentation/disclaimer-w32.texi create mode 100644 Documentation/gnu-music.texi create mode 100644 Documentation/internals.texi create mode 100644 Documentation/mail.texi diff --git a/Documentation/CodingStyle.texi b/Documentation/CodingStyle.texi new file mode 100644 index 0000000000..be26a0b5fb --- /dev/null +++ b/Documentation/CodingStyle.texi @@ -0,0 +1,401 @@ +\input texinfo @c -*-texinfo-*- +@setfilename CodingStyle.info +@settitle CodingStyle - standards while programming for GNU +LilyPond + +@node Top, , , (dir) +@top + + + + +@chapter CodingStyle - standards while programming for GNU +LilyPond + +() + +@unnumberedsec DESCRIPTION + + +We use these standards while doing programming for GNU LilyPond. If +you do some hacking, we appreciate it if you would follow this rules, +but if you don't, we still like you. + +Functions and methods do not return errorcodes. + +@quotation + +A program should be light and agile, its subroutines +connected like a string of pearls. The spirit and intent of +the program should be retained throughout. There should be +neither too little nor too much, neither needless loops nor +useless variables, neither lack of structure nor overwhelming +rigidity. + +A program should follow the 'Law of Least +Astonishment'. What is this law? It is simply that the +program should always respond to the user in the way that +astonishes him least. + +A program, no matter how complex, should act as a +single unit. The program should be directed by the logic +within rather than by outward appearances. + +If the program fails in these requirements, it will be +in a state of disorder and confusion. The only way to correct +this is to rewrite the program. + +-- Geoffrey James, "The Tao of Programming" +@end quotation + + +@unnumberedsubsec LANGUAGES + +C++, /bin/sh and Python are preferred. Perl is not. +Python code should use an indent of 8, using TAB characters. + +@unnumberedsubsec FILES + +Definitions of classes that are only accessed via pointers +(*) or references (&) shall not be included as include files. + +filenames + +@example + + ".hh" Include files + ".cc" Implementation files + ".icc" Inline definition files + ".tcc" non inline Template defs + +@end example + +in emacs: + +@example + + (setq auto-mode-alist + (append '(("\\.make$" . makefile-mode) + ("\\.cc$" . c++-mode) + ("\\.icc$" . c++-mode) + ("\\.tcc$" . c++-mode) + ("\\.hh$" . c++-mode) + ("\\.pod$" . text-mode) + ) + auto-mode-alist)) + +@end example + + +The class Class_name_abbreviation is coded in @file{class-name-abbr.*} + +@unnumberedsubsec INDENTATION + +in emacs: + +@example + + (add-hook 'c++-mode-hook + '(lambda() (c-set-style "gnu") + ) + ) + +@end example + +If you like using font-lock, you can also add this to your @file{.emacs}: + +@example + + (setq font-lock-maximum-decoration t) + (setq c++-font-lock-keywords-3 + (append + c++-font-lock-keywords-3 + '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face) + ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face)) + )) + +@end example + +@unnumberedsubsec CLASSES and TYPES: + +@example + + This_is_a_class + +@end example + +@unnumberedsubsec MEMBERS + +@example + + Class::member () + Type Class::member_type_ + Type Class::member_type () + +@end example + +the @code{type} is a Hungarian notation postfix for @code{Type}. See below + +@unnumberedsubsec MACROS + +Macros should be written completely in uppercase + +The code should not be compilable if proper macro declarations are not +included. + +Don't laugh. It took us a whole evening/night to figure out one of +these bugs, because we had a macro that looked like +@code{DECLARE_VIRTUAL_FUNCTIONS ()}. + +@unnumberedsubsec BROKEN CODE + +Broken code (hardwired dependencies, hardwired constants, slow +algorithms and obvious limitations) should be marked as such: either +with a verbose TODO, or with a short "ugh" comment. + +@unnumberedsubsec COMMENTS + +The source is commented in the DOC++ style. Check out doc++ at +@uref{http://www.zib.de/Visual/software/doc++/index.html} + +@example + + /* + C style comments for multiline comments. + They come before the thing to document. + [...] + */ + + /** + short description. + Long class documentation. + (Hungarian postfix) + + TODO Fix boring_member () + */ + class Class @{ + /** + short description. + long description + */ + + Data data_member_; + + /** + short memo. long doco of member () + @@param description of arguments + @@return Rettype + */ + Rettype member (Argtype); + + /// memo only + boring_member () @{ + data_member_ = 121; // ugh + @} + @}; + +@end example + + +Unfortunately most of the code isn't really documented that good. + +@unnumberedsubsec MEMBERS (2) + +Standard methods: + +@example + + ///check that *this satisfies its invariants, abort if not. + void OK () const + + /// print *this (and substructures) to debugging log + void print () const + + /** + protected member. Usually invoked by non-virtual XXXX () + */ + virtual do_XXXX () + + /**add some data to *this. + Presence of these methods usually imply that it is not feasible to this + via a constructor + */ + add (..) + + /// replace some data of *this + set (..) + +@end example + +@unnumberedsubsec Constructor + +Every class should have a default constructor. + +Don't use non-default constructors if this can be avoided: + +@example + + Foo f(1) + +@end example + +is less readable than + +@example + + Foo f; + f.x = 1 + +@end example + +or + +@example + + Foo f(Foo_convert::int_to_foo (1)) + +@end example + +@unnumberedsec HUNGARIAN NOTATION NAMING CONVENTION + + +Proposed is a naming convention derived from the so-called +@emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all +uppercase, with the parts of the names separated by underscores. + +@unnumberedsubsec Types + +@table @samp +@item @code{byte} + unsigned char. (The postfix _by is ambiguous) +@item @code{b} + bool +@item @code{bi} + bit +@item @code{ch} + char +@item @code{f} + float +@item @code{i} + signed integer +@item @code{str} + string class +@item @code{sz} + Zero terminated c string +@item @code{u} + unsigned integer +@end table + +@unnumberedsubsec User defined types + +@example + + /** Slur blah. blah. + (slur) + */ + class Slur @{@}; + Slur* slur_p = new Slur; + +@end example + +@unnumberedsubsec Modifiers + +The following types modify the meaning of the prefix. +These are preceded by the prefixes: + +@table @samp +@item @code{a} + array +@item @code{array} + user built array. +@item @code{c} + const. Note that the proper order is @code{Type const} + i.s.o. @code{const Type} +@item @code{C} + A const pointer. This would be equivalent to @code{_c_l}, but since any + "const" pointer has to be a link (you can't delete a const pointer), + it is superfluous. +@item @code{l} + temporary pointer to object (link) +@item @code{p} + pointer to newed object +@item @code{r} + reference +@end table + +@unnumberedsubsec Adjective + +Adjectives such as global and static should be spelled out in full. +They come before the noun that they refer to, just as in normal english. + +@example + +foo_global_i: a global variable of type int commonly called "foo". + +@end example + +static class members do not need the static_ prefix in the name (the +Class::var notation usually makes it clear that it is static) + +@table @samp +@item @code{loop_i} + Variable loop: an integer +@item @code{u} + Temporary variable: an unsigned integer +@item @code{test_ch} + Variable test: a character +@item @code{first_name_str} + Variable first_name: a String class object +@item @code{last_name_ch_a} + Variable last_name: a @code{char} array +@item @code{foo_i_p} + Variable foo: an @code{Int*} that you must delete +@item @code{bar_i_l} + Variable bar: an @code{Int*} that you must not delete +@end table + +Generally default arguments are taboo, except for nil pointers. + +The naming convention can be quite conveniently memorised, by +expressing the type in english, and abbreviating it + +@example + + static Array foo + +@end example + +@code{foo} can be described as "the static int-pointer user-array", so you get + +@example + + foo_static_l_arr + +@end example + + +@unnumberedsec MISCELLANEOUS + + +For some tasks, some scripts are supplied, notably creating patches, a +mirror of the website, generating the header to put over cc and hh +files, doing a release. + +Use them. + +The following generic identifications are used: + +@example + + up == 1 + left == -1 + right == 1 + down == -1 + +@end example + +Intervals are pictured lying on a horizontal numberline (Interval[-1] +is the minimum). The 2D plane has +x on the right, +y pointing up. + + +@bye diff --git a/Documentation/MANIFESTO.texi b/Documentation/MANIFESTO.texi new file mode 100644 index 0000000000..4900adb78f --- /dev/null +++ b/Documentation/MANIFESTO.texi @@ -0,0 +1,114 @@ +\input texinfo @c -*-texinfo-*- +@setfilename MANIFESTO.info +@settitle MANIFESTO - Rationale behind the GNU LilyPond project + +@node Top, , Goals for mudela, (dir) +@top +@menu +* MANIFESTO - Rationale behind the GNU LilyPond project::MANIFESTO - Rationale behind the GNU LilyPond project +@end menu + + + +@node MANIFESTO - Rationale behind the GNU LilyPond project, Goals for LilyPond, , Top +@menu +* Goals for LilyPond:: Goals for LilyPond +* Development constraints:: Development constraints +* Goals for mudela:: Goals for mudela +@end menu +@chapter MANIFESTO -- Rationale behind the GNU LilyPond project + + +@node Goals for LilyPond, Development constraints, MANIFESTO - Rationale behind the GNU LilyPond project, MANIFESTO - Rationale behind the GNU LilyPond project +@section Goals for LilyPond + +GNU LilyPond was written with some considerations in mind: + +@itemize @bullet +@item Describing a well-defined language for defining music. We call + this language (rather arrogantly) The Musical Definition Language + (mudela for short). GNU LilyPond reads a mudela sourcefile and outputs a + TeX file. +@item Providing an easy-to-use interface for typesetting music in + its broadest sense. This interface should be intuitive from a musical + point of view. By broadest sense we mean: it is designed for music + printed left to right in staffs, using notes to designate rythm and + pitch. +@item Generating high-quality output. Ideally it should be of a professional + quality. We'd like to render Herbert Chlapiks words, "Fine music + setting is not possible without a knowledgeable printer," untrue. +@item Making a system which is fully tweakable. It should be possible to + typeset a book on how not to typeset music. +@end itemize + +@node Development constraints, Goals for mudela, Goals for LilyPond, MANIFESTO - Rationale behind the GNU LilyPond project +@section Development constraints + +Further considerations while doing the programming + +@itemize @bullet +@item GNU LilyPond uses TeX for its output. This is not a key issue: in a + future version, GNU LilyPond might bypass TeX, but at the moment TeX + is convenient for producing output. +@item GNU LilyPond does not display notes directly, nor will it be rehacked + to be used interactively. GNU LilyPond writes output to a file. It + will not be extended to play music, or to recognize music. +@item GNU LilyPond is intended to run on Unix platforms, but it should + be portable to any platform which can run TeX and the GNU tools +@item GNU LilyPond is free. Commercial windows packages for setting music are + abundant. Free musicprinting software is scarce. For more thoughts on + this, please consult the @file{gnu-music} documentation. +@item GNU LilyPond is written in GNU C++. It will not be downgraded/ported to fit + broken systems. +@end itemize + +@node Goals for mudela, Top, Development constraints, MANIFESTO - Rationale behind the GNU LilyPond project +@section Goals for mudela + +The design of Mudela has been (perfect past tense, hopefully) an +ongoing process, the most important criteria being: + +@itemize @bullet +@item define the (musical) message of the composer as unambiguously as possible. + This means that, given a piece Mudela, it should be possible for a + program to play a reasonable interpretation of the piece. + + It also means that, given a piece of Mudela, it should be possible for a + program to print a score of the piece. +@item be intuitive, and easily readable (compared to, say, Musi*TeX input, + or MIDI :-), +@item be easily writable in ASCII with a simple texteditor +@end itemize + +Other considerations were (and will be): + +@itemize @bullet +@item be able to edit the layout without danger of changing the original + music (Urtext), +@item allow for adding different interpretations, again, + without danger of changing the original, +@item easy to create a conductor's score, + as well as the scores for all individual instruments, +@item provide simple musical manipulations, such as @emph{i} extracting a + slice of music from a previously defined piece, @emph{ii} extracting + only the rhythm from a piece of music, @emph{iii} transposing, etc., +@item easy to comprehend to both programmers and others. +@end itemize + +One of the things that (might) be here would be: feasible to use in a +graphic editor. We don't have experience with these beasts, so we +don't know how to do this. Comments appreciated. + +Musical pieces could be + +@itemize @bullet +@item Orchestral scores, (eg Mahler) +@item piano pieces (eg. Schubert, Rachmaninov), +@item pop songs (lyrics and chords), +@item Gregorian chants, +@item Bach multivoice organ pieces, +@item Short excerpts to be used in musicological publications. +@end itemize + + +@bye diff --git a/Documentation/disclaimer-w32.texi b/Documentation/disclaimer-w32.texi new file mode 100644 index 0000000000..30622c9b23 --- /dev/null +++ b/Documentation/disclaimer-w32.texi @@ -0,0 +1,19 @@ +\input texinfo @c -*-texinfo-*- +@setfilename disclaimer-w32.info +@settitle disclaimer-w32 + +@node Top, , , (dir) +@top + + +If you have the Cygnus gnu-windows32 port of the GNU utils, LilyPond +will work in Windows-NT (/95/98?). + +We still recommend you use Unix. In particular, use GNU/Linux: We've +been there, and we've seen it happen several times. It is @emph{much} +easier and quicker to install RedHat Linux and LilyPond than to +obtain, compile and install all the necessary tools to compile and run +LilyPond on Windows. + + +@bye diff --git a/Documentation/gnu-music.texi b/Documentation/gnu-music.texi new file mode 100644 index 0000000000..71bd946884 --- /dev/null +++ b/Documentation/gnu-music.texi @@ -0,0 +1,112 @@ +\input texinfo @c -*-texinfo-*- +@setfilename gnu-music.info +@settitle GNU Music project - manifesto + +@node Top, , Programs, (dir) +@top +@menu +* GNU Music project - manifesto:: GNU Music project - manifesto +@end menu + + + +@node GNU Music project - manifesto, Goal, , Top +@menu +* Goal:: Goal +* Requirements:: Requirements +* Components:: Components +* Programs:: Programs +@end menu +@chapter GNU Music project - manifesto + + +@node Goal, Requirements, GNU Music project - manifesto, GNU Music project - manifesto +@section Goal + + +The public deserves free tools for composing and printing. + +@node Requirements, Components, Goal, GNU Music project - manifesto +@section Requirements + +Emacs and TeX serve as useful examples of what programs by the GMP +should be. + +@table @samp +@item high-quality + The software should be of high-quality from the application view. +For example, the notation should be high-quality from an engraving +point of view, like TeX + +@item high-quality The software should be of high-quality point of + view, like all GNU software, it should have no limits, be fast, + etc. + +@item tweakable + Printed music has a lot of styles, and special symbols. It may be + unfeasible to provide and maintain lots of code that is hardwired + into the system. The tools should be extensible/programmable like + Emacs and TeX. + +@item easy to use. + That is, for technical users (that can read a manual). The learning + curve should be as flat as possible but not at the expense of comfort + of use and power. +@end table + +@node Components, Programs, Requirements, GNU Music project - manifesto +@section Components + +@table @samp +@item A set of music fonts + In development, the Feta font. +@item A typesetting engine + In development, included in LilyPond. + A system with rules on how to set properties of items to be printed + (up/down directions, breaking, dimensions, etc) + It should be suited to interactive typesetting (so, incremental + algorithms are needed) +@item A display engine + which can display clear notewriting in (say) an X-window + Ideally the system should cooperate with the typesetting engine +@item An ASCII language + In development, LilyPond has a language. + Having an ASCII format which enables urtext, and easy sharing (via + mail and news forums) encourages cooperation and exchange of music. +@item A printing engine + In development, included in LilyPond. +@item An input system + The natural way to enter composed music is singing or playing it. The + GMP should have module which can take keyboard input or microphone + input and convert it to computer data. (microphone input would be + difficult) +@item sequencing + (have no clue about this) +@item A scanning system + Having a system which can produce mudela from printed scores, greatly + simplifies creating a collection of music +@item A music-understanding system + (difficult) A system to generate accompaniments, figured bass, + automatic accompaniment, etc. +@item A performing system + A system which can play credible performances of abstract music + representations. LilyPond has a bare bones system, but it cannot + (yet) be described as "credible". +@end table + +@node Programs, Top, Components, GNU Music project - manifesto +@section Programs + +@itemize @bullet +@item A noninteractive typesetter, suited for batch jobs, and typesetting + existing music. This would couple the ASCII language, the printing + engine and the typesetting engine + LilyPond is currently representing this section. +@item A GUI for composing. This would combine the display engine, the input + system and the typesetting engine. +@item Libraries for reading and writing various audio/music/notation + formats. +@end itemize + + +@bye diff --git a/Documentation/internals.texi b/Documentation/internals.texi new file mode 100644 index 0000000000..2724c47cc3 --- /dev/null +++ b/Documentation/internals.texi @@ -0,0 +1,326 @@ +\input texinfo @c -*-texinfo-*- +@setfilename internals.info +@settitle LilyPond internals + +@node Top, , Spacing, (dir) +@top +@menu +* LilyPond internals:: LilyPond internals +@end menu + + + +@node LilyPond internals, Overview, , Top +@menu +* Overview:: Overview +* mudela:: mudela +* Request_engraver:: Request_engraver +* Items and spanners:: Items and spanners +* Dependencies:: Dependencies +* Breaking:: Breaking +* Spacing:: Spacing +@end menu +@chapter LilyPond internals + + +This documents some aspects of the internals of GNU LilyPond. Some of +this stuff comes from e-mail I wrote, some from e-mail others wrote, +some are large comments taken away from the headers. This page may be +a little incoherent. Unfortunately, it is also quite outdated. A +more thorough and understandable document is in the works. + +You should use @code{doc++} to take a peek at the sources. + +@node Overview, mudela, LilyPond internals, LilyPond internals +@section Overview + +GNU LilyPond is a "multi-pass" system. The different passes have been +created so that they do not depend on each other. In a later stage +some parts may be moved into libraries, or seperate programs, or they +might be integrated in larger systems. + +@table @samp + +@item Parsing: + +No difficult algorithms. 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 + +The music is walked through in time-order. The iterators which do the +walking report Music to Translators which use this information to +create elements, either MIDI or "visual" elements. The translators +form a hierarchy; the ones for paper output are Engravers, for MIDI +Performers. + +The translators swallow Music (mostly atomic gobs called Requests), +create elements, broadcast them to other translators on higher or same +level in the hierarchy: + +The stem of a voice A is broadcast to the staff which contains A, but +not to the stems, beams and noteheads of a different voice (say B) or +a different staff. The stem and noteheads of A are coupled, because +the the Note_heads_engraver broadcasts its heads, and the Stem_engraver catches +these. + +The engraver which agrees to handle a request decides whether to to +honor the request, ignore it, or merge it with other requests. Merging +of requests is preferably done with other requests done by members of +the same voicegroups (beams, brackets, stems). In this way you can put +the voices of 2 instruments in a conductor's score so they make chords +(the Beam requests of both instruments will be merged). + +@item Prebreaking + +Breakable stuff (eg. clefs and bars) are copied into pre and +postbreaks. + +@item Preprocessing + +Some dependencies are resolved, such as the direction of stems, beams, +and "horizontal" placement issues (the order of clefs, keys etc, +placement of chords in multi-voice music), + +@item Break calculation: + +The lines and horizontal positions of the columns are determined. + +@item Breaking + +Through some magical interactions with Line_of_score and Super_elem +(check out the source) the "lines" are produced. + +All other spanners can figure across which lines they are spread. If +applicable, they break themselves into pieces. After this, each piece +(or, if there are no pieces, the original spanner itself) throws out +any dependencies which are in the wrong line. + +@item Postprocesing: + +Some items and all spanners need computation after the Paper_column +positions are determined. Examples: slurs, vertical positions of +staffs. + +@item Output paper + +@end table + +@node mudela, Request_engraver, Overview, LilyPond internals +@section mudela + +Most information is stored in the form of a request. In music +typesetting, the user might want to cram a lot more symbols on the +paper than actually fits. To reflect this idea (the user asks more +than we can do), the container for this data is called Request. + +In a lot of other formats this would be called an 'Event' + +@table @samp +@item @code{Barcheck_req} + Checks during music processing if start of this voice element + coincides with the start of a measure. Handy to check if you left out + some voice elts. +@item @code{Note_req} + LilyPond has to decide if the ball should be hanging left or + right. This influences the horizontal dimensions of a column, and this + is why request processing should be done before horizontal spacing. + Other voices' frivolities may cause the need for accidentals, so this + is also for the to decide. The engraver can decide on positioning based on + ottava commands and the appropriate clef. +@item @code{Rest_req} + Typeset a rest. +@item @code{Span_req} + This type of request typically results in the creation of a @code{Spanner} +@item @code{Beam_req} + Start/stop a beam. + Engraver has to combine this request with the stem_request, since the + number of flags that a stem wants to carry will determine the + number of beams. +@item @code{Dynamic} + Each dynamic is bound to one note (a crescendo spanning multiple + notes is thought to be made of two "dynamics": a start and a stop). + Dynamic changes can occur in a smaller time than the length of its + note, therefore fore each @code{Dynamic} request carries a time, measured + from the start of its note. +@end table + +@node Request_engraver, Items and spanners, mudela, LilyPond internals +@section Request_engraver + +In the previous section the idea of Request has been explained, but +this only solves one half of the problem. The other half is deciding +which requests should be honored, which should merged with other +requests, and which should be ignored. Consider this input + +@example + + \type Staff < % chord + @{ \meter 2/4; [c8 c8] @} + @{\meter 2/4; [e8 e8] @} + > + +@end example + +Both the cs and es are part of a staff (they are in the same +Voice_group), so they should share meters, but the two [ ] pairs +should be merged. + +The judge in this "allocation" problem a set of brokers: the requests +are transmitted to so-called engravers which respond if they want to +accept a request eg, the @code{Notehead_engraver} will accept +@code{Note_req}s, and turn down @code{Slur_req}s. If the Music_iterator +cannot find a engraver that wants the request, it is junked (with a +warning message). + +After all requests have been either assigned, or junked, the Engraver +will process the requests (which usually means creating an @code{Item} +or @code{Spanner}). If a @code{Request_engraver} creates something, it +tells the enclosing context. If all items/spanners have been created, +then each Engraver is notified of any created Score_element, via a +broadcasting system. + +@unnumberedsubsec example: + +@example + + c4 + +@end example + +produces: + +@example + + Note_request (duration 1/4) + Stem_request (duration 1/4) + +@end example + +Note_request will be taken by a @code{Notehead_engraver}, stem_request +will be taken by a @code{Stem_beam_engraver}. @code{Notehead_engraver} +creates a @code{Notehead}, @code{Stem_beam_engraver} creates a +@code{Stem}. Both announce this to the Staff_engraver. Staff_engraver +will tell @code{Stem_beam_engraver} about the @code{Notehead}, which +will add the @code{Notehead} to the @code{Stem} it just created. + +To decide on merging, several engravers have been grouped. Please +check @file{init/engraver.ly}. + +@node Items and spanners, Dependencies, Request_engraver, LilyPond internals +@section Items and spanners + +The symbols that are printed, are generated by items and spanners +(staff-elements). An item has one horizontal position, whereas a +spanner spans several columns. + +@node Dependencies, Breaking, Items and spanners, LilyPond internals +@section Dependencies + +In music symbols depend on each other: the stems of a beam should +point in the same direction as the beam itself, so the stems of a beam +depend on the beam. In the same way do scripts depend on the direction +of the stem. To reflect this, LilyPond has the notion of dependency. +It works in the same fashion that @code{make} uses to build programs: +before a stem is calculated, its dependencies (the beam) should be +calculated. Before a slur is calculated, its dependencies (stems, +noteheads) should be calculated. + +@node Breaking, Spacing, Dependencies, LilyPond internals +@section Breaking + +So what is this PREBREAK and POSTBREAK stuff? + +Let's take text as an example. In German some compound +words change their spelling if they are broken: "backen" becomes +"bak-ken". TeX has a mechanism to deal with this, you would define +the spelling of "backen" in TeX in this way + + \discretionary@{bak-@}@{ken@}@{backen@} + +These 3 arguments are called "prebreak", "postbreak" and "nobreak" +text. + +The same problem exists when typesetting music. If a line of music is +broken, the next line usually gets a clef. So in TeX terms, the clef +is a postbreak. The same thing happens with meter signs: Normally the +meter follows the bar. If a line is broken at that bar, the bar along +with the meter stays on the "last" line, but the next line also gets a +meter sign after the clef. Using the previous notation, + + \discretionary@{bar meter@}@{clef meter@}@{ bar meter @} + +In GNU Lilypond, we have the same concepts (and the same +terminology). Each (nonrhythmic) symbol is typeset in a nonrhythmic column +At a breakpoint, multiple symbols are printed; symbols to be printed +if the line is not broken, symbols to appear on the previous line, and +on the next line if it is broken. + +@node Spacing, Top, Breaking, LilyPond internals +@section Spacing + +Some terminology: I call a vertical group of symbols (notes) which +start at the same time a "column". Each line of a score has notes in +it, grouped in columns. The difference in starting time between those +columns makes it possible to determine ideal distances between those +columns. + +Example: + +@example + + time -----> + + cols: col1 col2 col3 col4 + + voice1 1 1 + + voice2 2 2 2 2 + + (1 is a whole note, 2 a half note.) + + time_difference (col1 , col2) = 0.5 wholes, + time_difference (col1 , col3) = 1 wholes, + time_difference (col2 , col3) = 0.5 wholes, + etc. + +@end example + +these differences are translated into ideal distances + +@example + + distance (col1,col2) = 10 pt + distance (col1,col3) = 14.1 pt + distance (col2,col3) = 10 pt + etc. + +@end example + +as you can see, these distance are conflicting. So instead of +satisfying all those ideals simultaneously, a compromise is sought. + +This is Columbus' egg: GNU LilyPond attaches "springs" to each +column-pair. each spring has an equilibrium-position which is equal to +the above mentioned distance, so + +spring (col1, col2) and spring (col2,col3) try to push column 1 +and 3 away (to a distance of 20pt) from each other, whereas the spring +between col 1 and col 3 tries to pull those two together (to a +distance of 14.1 pt). The net result of this pushing and pulling is an +equilibrium situation (the pushing cancels the pulling), which can be +calculated as the solution of Quadratic program: it is the solution +with minimum potential energy, for you physicists out there. + +This algorithm for doing one line, gives a "badness" parameter for +each line (the potential energy). Now one can use TeX's algorithm for +making paragraphs (using this new version of "badness"): one should +try to minimise the overall badness of a paragraph. GNU LilyPond also +uses the concept of pre- and post-breaks. + +(actually, it is a bit more complicated: each column also has a +minimum distance to other columns, to prevent symbols from running +into symbols of other columns.) + + +@bye diff --git a/Documentation/mail.texi b/Documentation/mail.texi new file mode 100644 index 0000000000..7a6629630f --- /dev/null +++ b/Documentation/mail.texi @@ -0,0 +1,56 @@ +\input texinfo @c -*-texinfo-*- +@setfilename mail.info +@settitle mail + +@node Top, , , (dir) +@top + + + +For programs which are part of the GNU music project, the following +mailing list have been setup: + +@table @samp +@item info-gnu-music@@gnu.org + A moderated list for information on the GNU Music project, to + subscribe: send mail with subject "subscribe" to + info-gnu-music-request@@gnu.org. + + As this list is moderated, normal people should ask to + @email{drl@@gnu.org, David R. Linn} or + @email{hanwen@@cs.uu.nl, Han-Wen} to forward announces instead of + sending it to info-gnu-music@@gnu.org + +Since the GNU Music project currently only has LilyPond, this list is +mainly for announcing new versions of LilyPond. + +@uref{http://www.mail-archive.com/info-gnu-music@@gnu.org} + +@item help-gnu-music@@gnu.org + For help with programs from the GNU music project. To subscribe: send + mail with subject "subscribe" to + @email{help-gnu-music-request@@gnu.org} + + Since the GNU Music project currently only has LilyPond, this list is mainly about using and extending LilyPond. + + @uref{http://www.mail-archive.com/help-gnu-music@@gnu.org} + +@item bug-gnu-music@@gnu.org + If you have bugreports, you should send them to this list. If you want + to read all bugreports, you should subscribe to this list. To + subscribe: send mail with subject "subscribe" to + @email{bug-gnu-music-request@@gnu.org} + @uref{http://www.mail-archive.com/bug-gnu-music@@gnu.org} +@item gnu-music-discuss@@gnu.org, + For discussions concerning the GNU Music project, to subscribe: send + mail with subject "subscribe" to + @email{gnu-music-discuss-request@@gnu.org} + This list is archived at + @uref{http://www.mail-archive.com/gnu-music-discuss@@gnu.org} +@end table + +Announces of new versions will be sent to info-gnu-music and +gnu-music-discuss. + + +@bye diff --git a/debian/control b/debian/control index 5b0c3d387b..07d913fd21 100644 --- a/debian/control +++ b/debian/control @@ -2,18 +2,17 @@ Source: lilypond Section: tex Priority: optional Maintainer: Anthony Fok -Standards-Version: 2.5.0.0 +Standards-Version: 3.0.0 Package: lilypond Architecture: any -Depends: ${shlibs:Depends}, tetex-bin (>= 0.9.981031-2) -Recommends: python-base (>= 1.5.1), python-misc (>= 1.5.1), tetex-base (>= 0.9.981030-1), tetex-extra (>= 0.9.981030-1) +Depends: ${shlibs:Depends}, tetex-bin (>= 0.9.990310-1) +Recommends: python-base (>= 1.5.2-4), tetex-base (>= 0.9.990311-1), tetex-extra (>= 0.9.990311-1) Conflicts: musixtex-fonts, tetex-base (<< 0.9) -Description: The GNU Project music typesetter. +Description: A program for printing sheet music. LilyPond is a music typesetter. It produces beautiful sheet music using a high level description file as input. LilyPond is part of the GNU Project. - . URLs: http://www.cs.uu.nl/~hanwen/lilypond/ http://www.xs4all.nl/~jantien/lilypond/ diff --git a/stepmake/configure b/stepmake/configure index c20bd4b8c6..f0e6d92683 100755 --- a/stepmake/configure +++ b/stepmake/configure @@ -1200,307 +1200,6 @@ echo "configure:1177: checking language" >&5 # AC_STEPMAKE_TEXMF # AC_STEPMAKE_TEXMF_DIRS - if test "x$YODL" = "x"; then - for ac_prog in striproff -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1210: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_STRIPROFF'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$STRIPROFF"; then - ac_cv_prog_STRIPROFF="$STRIPROFF" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_STRIPROFF="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -STRIPROFF="$ac_cv_prog_STRIPROFF" -if test -n "$STRIPROFF"; then - echo "$ac_t""$STRIPROFF" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$STRIPROFF" && break -done -test -n "$STRIPROFF" || STRIPROFF="-echo no striproff" - - for ac_prog in yodl -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1245: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL"; then - ac_cv_prog_YODL="$YODL" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL="$ac_cv_prog_YODL" -if test -n "$YODL"; then - echo "$ac_t""$YODL" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL" && break -done -test -n "$YODL" || YODL="-echo no yodl" - - for ac_prog in yodl2html -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1280: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2HTML'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2HTML"; then - ac_cv_prog_YODL2HTML="$YODL2HTML" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2HTML="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2HTML="$ac_cv_prog_YODL2HTML" -if test -n "$YODL2HTML"; then - echo "$ac_t""$YODL2HTML" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2HTML" && break -done -test -n "$YODL2HTML" || YODL2HTML="-echo no yodl" - - for ac_prog in yodl2latex -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1315: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2LATEX'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2LATEX"; then - ac_cv_prog_YODL2LATEX="$YODL2LATEX" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2LATEX="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2LATEX="$ac_cv_prog_YODL2LATEX" -if test -n "$YODL2LATEX"; then - echo "$ac_t""$YODL2LATEX" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2LATEX" && break -done - - for ac_prog in yodl2man -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1349: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2MAN'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2MAN"; then - ac_cv_prog_YODL2MAN="$YODL2MAN" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2MAN="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2MAN="$ac_cv_prog_YODL2MAN" -if test -n "$YODL2MAN"; then - echo "$ac_t""$YODL2MAN" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2MAN" && break -done -test -n "$YODL2MAN" || YODL2MAN="-echo no yodl" - - for ac_prog in yodl2msless -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1384: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2MSLESS'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2MSLESS"; then - ac_cv_prog_YODL2MSLESS="$YODL2MSLESS" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2MSLESS="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2MSLESS="$ac_cv_prog_YODL2MSLESS" -if test -n "$YODL2MSLESS"; then - echo "$ac_t""$YODL2MSLESS" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2MSLESS" && break -done -test -n "$YODL2MSLESS" || YODL2MSLESS="-echo no yodl" - - for ac_prog in yodl2texinfo -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1419: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2TEXINFO'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2TEXINFO"; then - ac_cv_prog_YODL2TEXINFO="$YODL2TEXINFO" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2TEXINFO="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2TEXINFO="$ac_cv_prog_YODL2TEXINFO" -if test -n "$YODL2TEXINFO"; then - echo "$ac_t""$YODL2TEXINFO" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2TEXINFO" && break -done -test -n "$YODL2TEXINFO" || YODL2TEXINFO="-echo no yodl" - - for ac_prog in yodl2txt -do -# Extract the first word of "$ac_prog", so it can be a program name with args. -set dummy $ac_prog; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1454: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_YODL2TXT'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$YODL2TXT"; then - ac_cv_prog_YODL2TXT="$YODL2TXT" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_YODL2TXT="$ac_prog" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -YODL2TXT="$ac_cv_prog_YODL2TXT" -if test -n "$YODL2TXT"; then - echo "$ac_t""$YODL2TXT" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -test -n "$YODL2TXT" && break -done -test -n "$YODL2TXT" || YODL2TXT="-echo no yodl" - - YODL2LESS_DIR='$(bindir)/' - else - - - - - - - - - - export STRIPROFF YODL YODL2HTML YODL2LATEX YODL2MAN YODL2MSLESS YODL2TEXINFO YODL2TXT - fi - if test "x$YODL" = "-echo no yodl"; then - - echo "configure: warning: Did not find YODL (Yodl is Yet Oneother Document Language, see http://www.cs.uu.nl/~hanwen/yodl)" 1>&2 - warn_b=yes - - fi - - # AM_PATH_GTK(1.0.0,,AC_MSG_ERROR([please install proper version of gtk])) # AM_PATH_GTK__(0.9.4,,AC_MSG_ERROR([please install proper version of gtk--])) @@ -1509,7 +1208,7 @@ do # Extract the first word of "$ac_prog", so it can be a program name with args. set dummy $ac_prog; ac_word=$2 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:1513: checking for $ac_word" >&5 +echo "configure:1212: checking for $ac_word" >&5 if eval "test \"`echo '$''{'ac_cv_prog_MAKEINFO'+set}'`\" = set"; then echo $ac_n "(cached) $ac_c" 1>&6 else @@ -1539,8 +1238,6 @@ test -n "$MAKEINFO" && break done test -n "$MAKEINFO" || MAKEINFO="error" -# AC_CHECK_SEARCH_RESULT($YODL2TEXINFO, yodl, -# You should install Yodl 1.30.pre6 or better) trap '' 1 2 15 @@ -1702,15 +1399,6 @@ s%@INSTALL@%$INSTALL%g s%@PATHSEP@%$PATHSEP%g s%@DIRSEP@%$DIRSEP%g s%@DIR_DATADIR@%$DIR_DATADIR%g -s%@STRIPROFF@%$STRIPROFF%g -s%@YODL@%$YODL%g -s%@YODL2HTML@%$YODL2HTML%g -s%@YODL2LATEX@%$YODL2LATEX%g -s%@YODL2MAN@%$YODL2MAN%g -s%@YODL2MSLESS@%$YODL2MSLESS%g -s%@YODL2TEXINFO@%$YODL2TEXINFO%g -s%@YODL2TXT@%$YODL2TXT%g -s%@YODL2LESS_DIR@%$YODL2LESS_DIR%g s%@MAKEINFO@%$MAKEINFO%g CEOF diff --git a/stepmake/configure.in b/stepmake/configure.in index 892338dac1..296e9fbae0 100644 --- a/stepmake/configure.in +++ b/stepmake/configure.in @@ -26,13 +26,10 @@ AC_STEPMAKE_LOCALE # AC_STEPMAKE_MSGFMT # AC_STEPMAKE_TEXMF # AC_STEPMAKE_TEXMF_DIRS -AC_STEPMAKE_YODL # AM_PATH_GTK(1.0.0,,AC_MSG_ERROR([please install proper version of gtk])) # AM_PATH_GTK__(0.9.4,,AC_MSG_ERROR([please install proper version of gtk--])) AC_CHECK_PROGS(MAKEINFO, makeinfo, error) -# AC_CHECK_SEARCH_RESULT($YODL2TEXINFO, yodl, -# You should install Yodl 1.30.pre6 or better) AC_STEPMAKE_END diff --git a/stepmake/stepmake/texinfo-targets.make b/stepmake/stepmake/texinfo-targets.make index 1bb8bf6d7f..313f8a23e7 100644 --- a/stepmake/stepmake/texinfo-targets.make +++ b/stepmake/stepmake/texinfo-targets.make @@ -1 +1,3 @@ # empty + +local-WWW: $(addprefix $(outdir)/,$(TEXI_FILES:.texi=.html)) -- 2.39.5