--- /dev/null
+report(CodingStyle - standards while programming for GNU
+LilyPond)(Han-Wen Nienhuys and Jan Nieuwenhuizen)()()
+
+nsect(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, but use assert for
+checking status.
+
+quote(
+
+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"
+)
+
+
+nsubsect(LANGUAGES)
+
+C++, /bin/sh and python are preferred. Perl is not.
+
+nsubsect(FILES)
+
+Definitions of classes that are only accessed via pointers
+(*) or references (&) shall not be included as include files.
+
+filenames
+
+verb(
+ ".hh" Include files
+ ".cc" Implementation files
+ ".icc" Inline definition files
+ ".tcc" non inline Template defs
+)
+
+in emacs:
+
+verb(
+ (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))
+)
+
+
+The class Class_name_abbreviation is coded in file(class-name-abbr.*)
+
+
+nsubsect(INDENTATION)
+
+in emacs:
+
+verb(
+ (add-hook 'c++-mode-hook
+ '(lambda() (c-set-style "gnu")
+ )
+ )
+)
+
+If you like using font-lock, you can also add this to your file(.emacs):
+
+verb(
+ (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))
+ ))
+)
+
+nsubsect(CLASSES and TYPES:)
+
+verb(
+ This_is_a_class
+ AClass_name (for Abbreviation_class_name)
+)
+
+nsubsect(MEMBERS)
+
+verb(
+ Class::member()
+ Type Class::member_type_
+ Type Class::member_type()
+)
+
+the code(type) is a Hungarian notation postfix for code(Type). See below
+
+nsubsect(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()).
+
+nsubsect(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.
+
+nsubsect(COMMENTS)
+
+The source is commented in the DOC++ style. Check out doc++ at
+lurl(http://www.zib.de/Visual/software/doc++/index.html)
+
+verb(
+ /*
+ 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
+ }
+ };
+)
+
+
+Unfortunately most of the code isn't really documented that good.
+
+
+nsubsect(MEMBERS (2))
+
+Standard methods:
+
+verb(
+ ///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 (..)
+)
+
+nsubsect(Constructor)
+
+Every class should have a default constructor.
+
+Don't use non-default constructors if this can be avoided:
+
+verb(
+ Foo f(1)
+)
+
+is less readable than
+
+verb(
+ Foo f;
+ f.x = 1
+)
+
+or
+
+verb(
+ Foo f(Foo_convert::int_to_foo (1))
+)
+
+nsect(HUNGARIAN NOTATION NAMING CONVENTION)
+
+Proposed is a naming convention derived from the so-called
+em(Hungarian Notation).
+
+nsubsect(Hungarian)
+
+The Hungarian Notation was conceived by or at least got its name from,
+the hungarian programmer Charles Simonyi. It is a naming convention
+with the aim to make code more readable (for fellow programmers), and
+more accessible for programmers that are new to a project.
+
+The essence of the Hungarian Notation is that every identifier has a
+part which identifies its type (for functions this is the result
+type). This is particularly useful in object oriented programming,
+where a particular object implies a specific interface (a set of
+member functions, perhaps some redefined operators), and for
+accounting heap allocated memory pointers and links.
+
+nsubsect(Advantages)
+
+Another fun quote from Microsoft Secrets:
+
+quote(
+ The Hungarian naming convention gives developers the ability
+ to read other people's code relatively easily, with a minmum
+ number of comments in the source code. Jon De Vann estimated
+ that only about 1 percent of all lines in the Excel product
+ code consist of comments, but the code is still very
+ understandable due to the use of Hungarian: "if you look at
+ our source code, you also notice very few comments. Hungarian
+ gives us the ability to go in and read code..."
+)
+
+Wow! If you use Hungarian you don't have to document your software!
+Just think of the hours I have wasted documenting while this "silver bullet"
+existed. I feel so stupid and ashamed! (Didn't MMM-Brooks say `There is
+no silver bullet?' --HWN)
+
+
+nsubsect(Disadvantages)
+
+itemize(
+it()more keystrokes (disk space!)
+it()it looks silly code(get_slu_p())
+it()it looks like code from micro suckers
+it()(which) might scare away some (otherwise good?)
+ progammers, or make you a paria in the free
+ software community
+it()it has ambiguities
+it()not very useful if not used consistently
+it()usefullness in em(very large) (but how many classes is very large?)
+ remains an issue.
+)
+
+nsubsect(Proposal)
+
+itemize(
+it()learn about cut and paste / use emacs or vi
+ or lean to type using ten fingers
+it()Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
+it()use no, or pick less silly, abbrvs.
+it()use non-ambiguous postfixes code(identifier_name_type_modifier[_modifier])
+it()There is no need for Hungarian if the scope of the variable is small,
+ ie. local variables, arguments in function definitions (not
+ declarations).
+)
+
+Macros, code(enum)s and code(const)s are all uppercase,
+with the parts of the names separated by underscores.
+
+nsubsect(Types)
+
+description(
+dit(code(byte))
+ unsigned char. (The postfix _by is ambiguous)
+dit(code(b))
+ bool
+dit(code(bi))
+ bit
+dit(code(ch))
+ char
+dit(code(f))
+ float
+dit(code(i))
+ signed integer
+dit(code(str))
+ string class
+dit(code(sz))
+ Zero terminated c string
+dit(code(u))
+ unsigned integer
+)
+
+nsubsect(User defined types)
+
+verb(
+ /** Slur blah. blah.
+ (slur)
+ */
+ class Slur {};
+ Slur* slur_p = new Slur;
+)
+
+nsubsect(Modifiers)
+
+The following types modify the meaning of the prefix.
+These are preceded by the prefixes:
+
+description(
+dit(code(a))
+ array
+dit(code(array))
+ user built array.
+dit(code(c))
+ const. Note that the proper order is code(Type const)
+ i.s.o. code(const Type)
+dit(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.
+dit(code(l))
+ temporary pointer to object (link)
+dit(code(p))
+ pointer to newed object
+dit(code(r))
+ reference
+)
+
+nsubsect(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.
+
+verb(
+foo_global_i: a global variable of type int commonly called "foo".
+)
+
+static class members do not need the static_ prefix in the name (the
+Class::var notation usually makes it clear that it is static)
+
+description(
+dit(code(loop_i))
+ Variable loop: an integer
+dit(code(u))
+ Temporary variable: an unsigned integer
+dit(code(test_ch))
+ Variable test: a character
+dit(code(first_name_str))
+ Variable first_name: a String class object
+dit(code(last_name_ch_a))
+ Variable last_name: a code(char) array
+dit(code(foo_i_p))
+ Variable foo: an code(Int*) that you must delete
+dit(code(bar_i_l))
+ Variable bar: an code(Int*) that you must not delete
+)
+
+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
+
+verb(
+ static Array<int*> foo
+)
+
+code(foo) can be described as "the static int-pointer user-array", so you get
+
+verb(
+ foo_static_l_arr
+)
+
+
+
+nsect(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:
+
+verb(
+ up == 1
+ left == -1
+ right == 1
+ down == -1
+)
+
+Intervals are pictured lying on a horizontal numberline (Interval[-1]
+is the minimum). The 2D plane has +x on the right, +y pointing up.
+
+
--- /dev/null
+article(FAQ - GNU LilyPond FAQs)()()()
+
+DEFINEMACRO(question)(1)(subsect(ARG1))
+
+sect(Miscellaneous)
+
+question(HELP! I'm stuck!)
+
+Please read this document carefully. If you are still at loss,
+send your questions to the bf(mailing list), and not to authors
+directly.
+
+Note: relative paths are meant to be relative to the source directory
+
+sect(Installing)
+
+question(Wow, the webpages look really neat, but if I install the .exe
+file on my DOS/windows 3.11 machine, it doesn't work.)
+
+The DOS port is done with the cygnus gnu/windows32 port of the GNU utils.
+It does em(not) work with windows 3.x; you need Windows-NT (95/98?). This
+is not a recommendation, however. We recommend you use Unix, in
+particular, use GNU/Linux. For further information see file(README-W32).
+
+question(I get all kinds of errors while compiling file(parser.cc))
+
+LilyPond uses features of bison version 1.25. Please confirm that
+you are using a version 1.25 or better, that is bf(GNU) bison
+bf(1.25). Don't forget to do "make clean" after installing it. Don't
+forget to remove the stale file(bison.simple) as well.
+
+If the problem persists, then please send a bug report to the mailing list.
+
+question(I upgraded by applying a patch, and now my configure/build breaks.)
+
+Patches don't include automatically generated files, i.e.
+file(configure) and files generated by file(configure). Regenerate them
+yourself:
+verb(
+ autoconf
+ configure
+)
+You might need to create some extra "out" directories. Do this with
+verb(
+ make outdirs
+)
+question(Some of your neat scripts fail, what directories do you use:)
+
+[This only applies if you don't do code(make install), and develop out
+of the source directory]
+
+I have a directory which contains all our development projects
+verb(
+ ~/usr/
+)
+
+which looks like file(/usr/)
+verb(
+ bin/
+ share
+ lib/
+ share/
+ src/
+
+ etc....
+)
+
+The directory file(~/usr/src/) contains something like
+includefile(../stepmake/Documentation/layout.yo)
+)
+
+~/usr/src/bin is in the PATH, and contains symlinks to the
+compiled executables.
+
+question(Is there an emacs mode?)
+
+Yes. It is included with the source archive as mudela-mode.el. If
+you have an rpm it is in /usr/doc/lilypond-X/. You have to install it
+yourself.
+
+sect(Language: mudela)
+
+question(Why can't you type code(#c) in stead of code(cis) ?)
+
+We think that code(#c) looks as if you are entering the symbols to
+print (which you are not; remember, you're entering the musical
+content in Mudela)
+
+
+question(Why do I have to type the accidentals to the note if I specified them?)
+
+Take this example
+verb(
+ cis cis
+)
+Independently of how it was written and what the current key was, you
+would say that you are playing and reading "two C-sharp" notes. We
+have tried to make the language somewhat context-free. Of course
+sheet music is not context-free. Unfortunately, sheet music is also 2
+dimensional, and ASCII is not.
+
+Technically it would be feasible to have the Interpreting phase do
+tricky things to add (or leave out) the accidentals, but we think that
+it is impractical: it hampers the readability and portability of your
+source, since you need LilyPond to fill in the details and actually
+make sense of it.
+
+
+question(What is code(cis) anyway)
+
+code(cis) is the dutch naming for C-sharp. The notes are named
+a, b,.., g. The suffix -is means sharp, and -es flat. This system is
+common in a number of languages (such as swedish, dutch, german.)
+Certain other languages (such as English, French and Italian) just add
+the word for "sharp" to the notename.
+
+We chose the Dutch system, because we're dutch. You are free to chose
+whatever names you like; they are user definable.
+
+
+question(Why are [] around the notes, and () inbetween?)
+
+[] designate beams, a note can only be in one beam at the same
+time. () is a slur, which connects notes. You need to be able to
+specify
+verb(
+ a()a()a
+)
+
+question(I want to insert some TeX commands.)
+
+You shouldn't: it's against LilyPond philosophy to have typesetting
+commands in the mudela source. Moreover, this would be difficult.
+LilyPond uses TeX like a glorified output engine: the output consists
+of (x,y) positions and symbols. You can only sensibly do TeX stuff in
+the symbol string. You can access the symbol string easily for some
+symbols (notably lyrics and code(^"text") commands).
+
+
+sect(Do you support ...)
+
+question(Do you support pop songs (chords, single staff, lyrics)?)
+
+Yes, see the file(twinkle-pop) example.
+
+
+question(Do you support guitar chord diagrams?)
+
+No, not yet. We ourselves don't play guitar, and don't know the
+fine points of this notation. We would welcome anyone who could give
+this a try.
+
+question(Do you support TAB notation?)
+
+No. The same as for the previous question goes, but TAB is a lot
+more work than diagrams (TAB needs modification of Parser, Lexer,
+Staff, Notehead, Stem code and all the code that creates these graphic
+elements.)
+
+question(Do you support multiple staff-sizes?)
+
+Yes and no. At this time you can choose between 11, 13, 16, 19,
+20, 23 and 20 pt staff-size. The sizes can't be changed per staff
+(yet). Look at file(standchen.ly) for an example.
+
+
+sect(How do I ....)
+
+question(How do I change the TeX layout?)
+
+See file(lilyponddefs.tex), it has some comments. Or use file(ly2dvi).
+
+question(How do I place lyrics under em(each) of the staves in a
+score, as choral music. I can work out how to put lyrics for each line
+all under the top line, or at the bottom but not between!)
+
+You change the order lyrics and staves. You have to name all
+staves (lyric and melodic), otherwise they will end up in the same
+staff/lyricline
+verb(
+ \score {
+ < \melodic \type Staff = "treble" \trebleMelody
+ \lyric \type Lyrics = "tlyrics" \trebtext
+ \type Staff = "bass" \melodic \bassMelody
+ \lyric \type Lyrics = "blyrics" \basstext
+ >
+ \paper { }
+ }
+)
+
+question(How do I put more than one marking on a note.)
+
+You can stack them
+verb(
+ c4^"a"^"b"
+)
+or use spacing-notes to put markings at different horizontal positions
+verb(
+ < c1
+ { s4\ff s4^"text" s4-\marcato s4 }
+ >
+)
+This also works for crescendi, eg,
+verb(
+ < c1
+ { s4\< s2 \! s4 }
+ >
+)
+
+
+question(How do I get bar numbers?)
+
+See file(init/engraver.ly). You have to uncomment some entries. To
+do this `portably' you should redefine some engravers in your own
+source files. Check out file(init/rhythm.ly).
+
+
+sect(Development)
+
+question(Could you implement feature XXXX? It is really easy, just extend
+the syntax to allow YYYY!)
+
+If it is reasonable, I'll add XXXX to the TODO list. In general
+finding a cute syntax (such as YYYY) isn't very hard. The complicated
+issue how to adapt the internals to do XXXX. The parser is really a
+simple front end to the complicated internals.
+
+
+question(Can I join in on LilyPond development? How do I do this?)
+
+LilyPond development is open for anyone who wants to join. We try
+to use a Bazaar style development model for LilyPond, see
+lurl(http://locke.ccil.org/~esr/writings/cathedral.html.) This means:
+frequent releases, everyone can send in a patch or do suggestions and
+all development discussions are public.
+
+To be precise, discussions take place on the gnu-music-discuss mailing
+list, which is open for subscription to everyone.
+
+
+question(I want to implement XXXX! Should I do this?)
+
+There might be better ways of doing XXXX, so it's a good thing to
+ask about this before you start hacking. If you want to keep in touch
+with current developments, you should subscribe to the mailing list
+(see the "links" section of the documentation).
+
+
+question(Is there a GUI frontend? Should I start building one?)
+
+LilyPond currently has no graphical interface. The authors seriously
+doubt if a simple-minded approach (dragging and dropping notes) is any
+easier or quicker to use than mudela. But for composing a graphical
+environment probably is indispensable.
+
+In any case email(Derek Wyatt)(wyatt@?.edu) is working on embryonal GTK
+based editor. There also a GUI package RoseGarden that could be
+extended to output mudela.
+
+
+question(I want to implement XXXX! How should I do this?)
+
+Your best bet of getting me to include code, is to present it as a
+"fait accompli", i.e., to send me a patch.
+
+
+question(I made some code, how do I get you to include it?)
+
+Send in a patch:
+verb(
+ diff -urN old-file new-file > patch
+)
+or
+verb(
+ diff -urN old-directory/ new-directory/ > patch
+)
+Alternatively, you can use issue the command
+verb(
+ make diff
+)
+
+Don't forget to put your name and e-mail address
+in the file(AUTHORS.pod) file, or you won't get credits :-]
+
+
+question(How do I learn the C++ code?)
+
+The entry point is in code(main()). Good luck. :-)
+
+Seriously, read, reread and reread internals and CodingStyle, and
+just start anywhere.
+
+Anywhere? Well, most of the comment doco are in the header files, so
+your best bet would be code(less lily/include/*.hh). Some of the most
+important data-structures are to be found in:
+verb(
+ - *request.hh
+ - engraver.hh
+ - performer.hh
+ - translator.hh
+ - score-elem.hh
+ - music.hh
+ - music-list.hh
+ - music-iterator.hh
+ - item.hh
+ - spanner.hh
+)
+
+question(Why GPL?)
+
+Yes.
+
+
+question(Your make system does not adhere to GNU coding standards, could you
+please fix it?)
+
+No. We have evaluated the standard GNU combination for compiling
+programs (autoconf, automake, libtool) and found to be inadequate in
+several respects. More detailed argumentation is included with
+LilyPond's generic make package code(StepMake)
+(see file(stepmake-x.x.x/Documentation/automake.urgh))
+
+LilyPond already compiles into a different directory ((the different
+directory is called out/, there is one in every source directory).
+make distclean essentially reduces to file(rm -f out/*) in every directory
+
+
+question(gdb crashes when I debug!)
+
+Upgrade to 4.17.
+
+question(Why do I need g++ >= 2.7?)
+
+By using g++, GNU LilyPond is portable to all platforms which support
+g++ (there are quite a few). Not having to support other compilers
+saves us a em(lot) of trouble.
+
+
+sect(Running)
+
+
+question(I use dvilj4, and there are lots of warning messages for the
+printing)
+
+You should use dvips and ghostscript to print the code(dvi) output:
+the slurs and beams are PS code(\special) commands.
+
+
+question(My symbols are all messed up after I upgraded, I get the
+wrong symbols and dvi-checksum errors!)
+
+We obviously mucked with the fonts in the upgrade. Remove em(all)
+previous fonts, including the file(.pk) and file(.tfm) fonts in
+file(/var/lib/texmf). A script automating this has been included, see
+file(buildscripts/clean-fonts.sh).
+
+
+question(The beams and slurs are gone if use the XDvi magnifying glass!?)
+
+The beams and slurs are done in PostScript. XDvi doesn't show
+PostScript in the magnifying glass. Complain to the XDvi maintainers.
+
+
+question(I don't get midi-output, even if I use bf(-M)!)
+
+Your \score should include a \midi block, eg.
+verb(
+ \score {
+ \melodic { c4 c g g }
+ \paper {}
+ \midi {
+ \output "myfile.mid";
+ \tempo 4=70;
+ }
+ }
+)
+The bf(-M) option was added to LilyPond because processing the \paper
+block is so slow.
+
+question(A lot of musical stuff doesn't make it to the MIDI file, eg.
+dynamics, articulation, etc.)
+
+The MIDI output was originally put in as a proof that MIDI could be
+done, and as a method of proof"reading" the input. The MIDI support
+is by no means finished. Patches appreciated.
+
+sect(Windows32)
+
+question(I downloaded the windows32 port, and it doesn't match the website!)
+
+The website is usually made from the latest snapshots. Binary releases,
+in particular the windows32 binaries, are only made every once in a while.
+They may lag several versions behind the latest version.
+
+question(But i want a native DOS/Windows-NT/95 port)
+
+Reconsider. Try Linux. It's fun!
+
--- /dev/null
+article(GNU Music project - manifesto)(Han-Wen Nienhuys and Jan Nieuwenhuizen)()
+
+sect(Goal)
+
+Provide musicians with free software for
+
+itemize(
+it()composing
+it()engraving
+it()playing
+it()sequencing
+it()interchanging music
+it()arranging
+it()performing
+it()Metacomposing
+)
+
+These systems should encourage laymen to take up composing, in the
+same way that GNU tools have created a whole new generation of
+programmers.
+
+The public deserves free tools for composing and printing.
+
+
+sect(Requirements)
+
+Emacs and TeX() serve as useful examples of what programs by the GMP
+should be.
+
+description(
+dit(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()
+
+dit(high-quality) The software should be of high-quality point of
+ view, like all GNU software, it should have no limits, be fast,
+ etc.
+
+dit(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.
+
+dit(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.
+)
+
+sect(Components)
+
+description(
+dit(A set of music fonts)
+ In development, the Feta font.
+dit(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)
+dit(A display engine)
+ which can display clear notewriting in (say) an X-window
+ Ideally the system should cooperate with the typesetting engine
+dit(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.
+dit(A printing engine)
+ In development, included in LilyPond.
+dit(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)
+dit(sequencing)
+ (have no clue about this)
+dit(A scanning system)
+ Having a system which can produce mudela from printed scores, greatly
+ simplifies creating a collection of music
+dit(A music-understanding system)
+ (difficult) A system to generate accompaniments, figured bass,
+ automatic accompaniment, etc.
+dit(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".
+)
+
+sect(Programs)
+
+itemize(
+it()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.
+it()A GUI for composing. This would combine the display engine, the input
+ system and the typesetting engine.
+it()Libraries for reading and writing various audio/music/notation
+ formats.
+)
+
+Find sponsors. This project will take a long time, and in its infant
+stages, having a hard and small core which does a lot of work, is more
+efficient than lots of people doing small subprojects. Finanicial
+support would be desirable.
+
--- /dev/null
+COMMENT(i don't get this)
+mailto(janneke@gnu.org)
+COMMENT(
+ (PIPETHROUGH(echo -n `date '+%d/%b/%y'|tr '[a-z]' '[A-Z]'`)())
+)
+manpage(LilyPond)
+ (1)
+ (1998)
+ (The LilyPond package)
+ (The GNU Project Music Typesetter)
+
+metalC(Automatically generated by yodl(1) from lilypond.yo.)
+
+manpagename(LilyPond)(the GNU Music Typesetter)
+cindex(LilyPond)
+
+COMMENT(nodes and menus by hand, for now)
+node(Author convert-mudela)(LilyPond)(Invoking LilyPond)(Programs)
+menu(
+mit(Invoking LilyPond)( Command options supported by file(LilyPond))
+mit(Disclaimer LilyPond)( Disclaimer)
+mit(Features LilyPond)( Features)
+mit(Problems LilyPond)( Problems)
+mit(Files LilyPond)( Files)
+mit(Environment LilyPond)( Environment)
+mit(Bugs LilyPond)( Bugs)
+mit(See Also LilyPond)( See Also)
+mit(Remarks LilyPond)( Remarks)
+mit(History LilyPond)( History)
+mit(Author LilyPond)( Author)
+)
+
+node(LilyPond)(Invoking LilyPond)(Features LilyPond)(LilyPond)
+
+manpagesynopsis()
+ bf(lilypond) [OPTION]... [MUDELA-FILE]...
+
+manpagedescription()
+
+verbinclude(../BLURB.in)
+
+manpageoptions()
+description(
+dit(-I,--include=FILE)
+ add file(FILE) to the search path for input files.
+dit(-M,--midi)
+ This disables TeX output. If you have a \midi definition, it will do the
+ midi output only.
+dit(-d,--dependencies)
+ Also output rules to be included in Makefile.
+dit(-D,--debug)
+ Turn debugging info on. GNU LilyPond reads the file file(.dstreamrc),
+ which lists what functions and classes may produce copious debugging
+ output.
+dit(-t,--test)
+ Switch on any experimental features. Not for general public use.
+dit(-w,--warranty)
+ Show the warranty with which GNU LilyPond comes. (It comes with
+ bf(NO WARRANTY)!)
+dit(-o,--output=FILE)
+ Set the default output file to file(FILE).
+dit(-h,--help)
+ Show a summary of usage.
+dit(-i,--init=FILE)
+ Set init file to file(FILE) (default: file(init.ly)).
+dit(--include, -I=DIRECTORY)
+ Add file(DIRECTORY) to the search path for input files.
+dit(--ignore-version, -V)
+ Make incompatible mudela version non-fatal.
+dit(--find-fourths, -Q)
+ Warn about melodic intervals larger than a fourth. Useful for
+ converting absolute octave mode stuff to relative octaves.
+)
+
+node(Invoking LilyPond)(Features LilyPond)(Disclaimer LilyPond)(LilyPond)
+manpagesection(FEATURES)
+
+This is an overview of the features that GNU LilyPond supports. For
+details on how to use them, you should consult the Mudela tutorial,
+which is included with the package.
+
+
+itemize(
+it()ASCII script input, with identifiers (for music reuse),
+ customizable notenames, customisable fontset.
+it()MIDI output lets you check if you have entered the correct notes.
+it()MIDI to Mudela conversion through the mi2mu program.
+it()Multiple staffs in one score. Each staff can have different meters.
+it()Beams, slurs, ties, chords, super/subscripts (accents and text)
+ triplets, general n-plet (triplet, quadruplets, etc.), lyrics,
+ transposition dynamics (both absolute and hairpin style).
+it()Multiple voices within one staff; beams optionally shared
+ between voices. Up to four voices is handled cleanly.
+it()Multiple scores within one input file. Each score is output to
+ a different file.
+it()Clef changes, meter changes, cadenza-mode, key changes, repeat bars.
+)
+
+node(Features LilyPond)(Disclaimer LilyPond)(Problems LilyPond)(LilyPond)
+manpagesection(DISCLAIMER)
+
+GNU LilyPond is copyright 1996-1998 by its authors. GNU LilyPond is
+distributed under the terms of the GNU General Public License. GNU LilyPond
+is provided without any warranty what so ever.
+GNU LilyPond may be freely distributed. For further information consult
+the GNU General Public License, from the file file(COPYING).
+
+node(Disclaimer LilyPond)(Problems LilyPond)(Files LilyPond)(LilyPond)
+manpagesection(PROBLEMS)
+
+There is an extensive list of todoes and bugs. See file(TODO). If you
+have a problem you should try to find out
+
+itemize(
+it()If the bug has been fixed in a newer release.
+it()If the bug has been found earlier, consult file(TODO) and file(BUGS).
+)
+
+If you have found a bug, then you should send a bugreport.
+
+itemize(
+it()Send a copy of the input which causes the error.
+it()Send a description of the platform you use.
+it()Send a description of the LilyPond version you use
+ (with compile/configure options please).
+it()Send a description of the bug itself.
+it()Send it to email(bug-gnu-music@gnu.org) (you don't have to subscribe
+ to this mailinglist).
+)
+
+node(Problems LilyPond)(Files LilyPond)(Environment LilyPond)(LilyPond)
+manpagefiles()
+description(
+dit(file(init.ly))
+ The initialisation file with symbol tables etc. It
+ includes files from the directory file(init/).
+)
+
+node(Files LilyPond)(Environment LilyPond)(Bugs LilyPond)(LilyPond)
+manspagesection(environment)
+
+description(
+dit(LILYINCLUDE)
+ additional directories for finding lilypond data. The
+ format is like the format of file(PATH).
+dit(LANG)
+ selects the language for the warning messages of LilyPond.
+)
+
+node(Environment LilyPond)(Bugs LilyPond)(See Also LilyPond)(LilyPond)
+manpagebugs()
+
+Lots of them. See file(TODO) and file(BUGS)
+
+node(Bugs LilyPond)(See Also LilyPond)(Remarks LilyPond)(LilyPond)
+manpageseealso()
+
+description(
+dit(internals)
+ On technical details of LilyPond
+dit(mudela-man)
+ On the input format. This is a LilyPond-enhanced LaTeX document.
+dit(MANIFESTO)
+ Goals of the GNU LilyPond project.
+dit(FAQ)
+ The GNU LilyPond FAQ list
+dit(GNU url(LilyPond)(http://www.cs.uu.nl/people/hanwen/lilypond/index.html))
+ has her own webpage. This webpage contains the MIDI, GIF and PS files for
+ some standard music files. It also has the complete LilyPond documentation
+)
+
+GNU LilyPond is
+updated very frequently, the latest version is always available at:
+lurl(ftp://pcnov095.win.tue.nl/pub/lilypond). This FTP site is mirrored
+at a number of sites; consult the project web pages for information
+about mirrors.
+
+For programs which are part of the GNU music project, the following
+mailing list have been setup:
+
+description(
+dit(email(info-gnu-music@gnu.org))
+ For information on the GNU Music project, to subscribe: send mail with
+ subject "subscribe" to email(info-gnu-music-request@gnu.org)
+dit(email(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)
+dit(email(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)
+dit(email(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)
+)
+
+Announces of new versions will be sent to info-gnu-music and
+gnu-music-discuss.
+
+node(See Also LilyPond)(Remarks LilyPond)(History LilyPond)(LilyPond)
+manpagesection(REMARKS)
+
+GNU LilyPond has no connection with the music package Rosegarden, other
+than the names being similar (:-)
+
+node(Remarks LilyPond)(History LilyPond)(Author LilyPond)(LilyPond)
+manpagesection(HISTORY)
+cindex(History)
+
+(for a detailed changelog, see file(NEWS))
+
+GNU LilyPond's roots lie in MPP, a preprocessor to the rather arcane
+MusiXTeX macro package for TeX. A friend of mine, Jan Nieuwenhuizen
+wrote the first 44 versions (0.01 to 0.44), then his program caught my
+attention, and I was slowly sucked in to the interesting problem of
+easily producing beautifully printed music. I contributed some
+code. We soon realised that MPP's design was too fundamentally broken
+to be repaired, so it was decided to rewrite MPP. We debated a lot about
+the requirements to an inputformat (fall 1995). I sat down and started
+with a parser-first, bottom-up rewrite called mpp95 (which totally
+failed, obviously).
+
+After long and hard thinking, I came up with an algorithm for the
+horizontal spacing of multiple staffs (april 1996) I coded it (and did
+not test it). After starting with this fundamental piece, I slowly
+added the stages which come before spacing, and after. A half year
+later, I had a first working version, (october 1996). I announced
+Patchlevel 0.0.7 (or 8) to the mutex list after asking some technical
+details on spacing; it was downloaded approximately 4 times. Then I
+got the hang of it, and in the subsequent two months, I coded until it
+had doubled in size (pl 23).
+
+Most the other history is described in the NEWS file. The first large
+scale release (0.1) was done after approximately 78 patchlevels on
+August 1, 1997.
+
+node(History LilyPond)(Author LilyPond)(Ly2dvi)(LilyPond)
+manpageauthor()
+cindex(Author)
+
+Please consult the documentation file file(AUTHORS.txt) for more detailed
+information, and small contributions.
+
+itemize(
+it()nemail(Han-wen Nienhuys)(hanwen@cs.uu.nl)
+ lurl(http://www.cs.uu.nl/people/hanwen)
+it()nemail(Jan Nieuwenhuizen)(janneke@gnu.org)
+ lurl(http://www.digicash.com/~jan)
+)
--- /dev/null
+mailto(janneke@gnu.org)
+manpage(LilyPond)
+ (1)
+ (1998)
+ (The LilyPond package)
+ (Ly2dvi)
+
+metalC(Automatically generated by yodl(1) from ly2dvi.yo.)
+
+node(Author LilyPond)(Ly2dvi)(Invoking Ly2dvi)(Programs)
+manpagename(Ly2dvi)(convert mudela to DVI)
+
+menu(
+mit(Invoking Ly2dvi)( Command options supported by file(Ly2dvi))
+mit(Features Ly2dvi)( Features)
+mit(Environment Ly2dvi)( Environment)
+mit(Files Ly2dvi)( Files)
+mit(See Also Ly2dvi)( See Also)
+mit(Bugs Ly2dvi)( Bugs)
+mit(Remarks Ly2dvi)( Remarks)
+mit(Author Ly2dvi)( Author)
+)
+
+manpagedescription()
+ly2dvi is a shell script which creates input file for LaTeX,
+based on information from the output files from lilypond.
+The script handles multiple files. If a mudela file name is
+specified lilypond is run to make an output (TeX) file.
+
+One or more LaTeX files are created, based on information found
+in the output (TeX) files, and latex is finally run to create
+one or more DVI files.
+
+node(Ly2dvi)(Invoking Ly2dvi)(Features Ly2dvi)(Ly2dvi)
+manpagesynopsis()
+
+ ly2dvi [options] inputfile[.ly] [....]
+
+manpageoptions()
+
+description(
+dit(-D,--debug)
+ Set debug mode. There are two levels - in level one some debug
+ info is written, in level two the command bf(set -x) is run, which
+ echoes every command in the ly2dvi script.
+dit(-F,--headers=)
+ Name of additional LaTeX headers file. This is included in the
+ tex file at the end of the headers, last line before code(\begin{document})
+dit(-H,--Heigth=)
+ Set paper heigth (points). Used together with width and LaTeX name of
+ papersize in case of papersize unknown to ly2dvi.
+dit(-F,--headers=)
+ Name of additional LaTeX headers file. This is included in the
+ tex file at the end of the headers, last line before code(\begin{document})
+dit(-K,--keeplilypond)
+ Keep LilyPond output after the run.
+dit(-L,--landscape)
+ Set landscape orientation - portrait is the default.
+ (bf(-L) produces code(\usepackage[landscape]{article}))
+dit(-N,--nonumber)
+ Switch off page numbering.
+dit(-O,--orientation=)
+ Set orientation landscape - obsolete, use bf(-L) instead.
+dit(-W,--Width=)
+ Set paper width (points). Used together with heigth and LaTeX name of
+ papersize in case of papersize unknown to ly2dvi.
+dit(-d,--dependencies)
+ Tell lilypond to make dependencies file.
+dit(-h,--help)
+ Print help.
+dit(-k,--keeply2dvi)
+ Keep the LaTeX file after the run.
+dit(-l,--language=)
+ Specify LaTeX language.
+ (bf(-l norsk) produces code(\usepackage[norsk]{babel})).
+dit(-o,--output=)
+ Set output directory.
+dit(-p,--papersize=)
+ Specify papersize.
+ (bf(-p a4) produces code(\usepackage[a4paper]{article}))
+dit(-s,--separate)
+ Normally all output files are included into one LaTeX file.
+ With this switch all files are run separately, to produce one
+ DVI file for each.
+)
+
+node(Invoking Ly2dvi)(Features Ly2dvi)(Environment Ly2dvi)(Ly2dvi)
+manpagesection(Features)
+
+ly2dvi responds to several parameters specified in the mudela
+file. They are overridden by corresponding command line options.
+
+description(
+dit(language="";)
+ Specify LaTeX language
+dit(latexheaders="";)
+ Specify additional LaTeX headers file
+dit(orientation="";)
+ Set orientation.
+dit(paperlinewidth="";)
+ Specify the width (pt, mm or cm) of the printed lines.
+dit(papersize="";)
+ Specify name of papersize.
+)
+
+node(Features Ly2dvi)(Environment Ly2dvi)(Files Ly2dvi)(Ly2dvi)
+manpagesection(Environment)
+
+description(
+dit(LILYINCLUDE)
+ Additional directories for input files.
+dit(TMP)
+ Temporary directory name. Default is /tmp
+)
+
+node(Environment Ly2dvi)(Files Ly2dvi)(See Also Ly2dvi)(Ly2dvi)
+manpagesection(Files)
+
+file(titledefs.tex) is inspected for definitions used to extract
+additional text definitions from the mudela file. In the current
+version the following are defined:
+
+description(
+dit(title)
+ The title of the music. Centered on top of the first page.
+dit(subtitle)
+ Subtitle, centered below the title.
+dit(composer)
+ Name of the composer, rightflushed below the subtitle.
+dit(arranger)
+ Name of the arranger, rightflushed below the composer.
+dit(instrument)
+ Name of the instrument, leftflushed at same level as the composer.
+)
+
+file(/usr/local/share/lilyrc /etc/lilyrc $HOME/.lilyrc ./.lilyrc)
+are files to set up default running conditions/variables, Bourne shell
+syntax. All files are parsed, in the shown sequence. The variables are
+overridden by variables in the mudela file, and by command line options.
+In the current version the following are allowed:
+
+description(
+dit(LANGUAGE=)
+ Specify LaTeX language.
+dit(LATEXHF=)
+ Specify additional LaTeX headers file
+dit(LILYINCLUDE=)
+ Additional directories for input files.
+dit(ORIENTATION=)
+ Set orientation - portrait is the default.
+dit(OUTPUTDIR=)
+ Set output directory.
+dit(PAPERSIZE=)
+ Specify name of papersize.
+dit(PHEIGTH=)
+ Specify paperheight (points - an inch is 72.27, a cm is 28.453 points).
+dit(TMP=)
+ Temporary directory name.
+dit(PWIDTH=)
+ Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points).
+)
+
+node(Files Ly2dvi)(See Also Ly2dvi)(Bugs Ly2dvi)(Ly2dvi)
+manpagesection(See Also)
+
+lilypond(1), tex(1), latex(1)
+
+node(See Also Ly2dvi)(Bugs Ly2dvi)(Remarks Ly2dvi)(Ly2dvi)
+manpagesection(Bugs)
+
+If you have found a bug, you should send a bugreport.
+
+itemize(
+it()Send a copy of the input which causes the error.
+it()Send a description of the platform you use.
+it()Send a description of the LilyPond and ly2dvi version you use.
+it()Send a description of the bug itself.
+it()Send it to email(bug-gnu-music@gnu.org) (you don't have to subscribe
+ to this mailinglist).
+)
+
+node(Bugs Ly2dvi)(Remarks Ly2dvi)(Author Ly2dvi)(Ly2dvi)
+manpagesection(Remarks)
+
+Many papersizes are now supported. Information on other sizes
+(LaTeX names, horizontal and vertical sizes) should be mailed to
+the author or to the mailing list.
+
+Supported papersizes are:
+
+a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD,
+archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal,
+letter, note
+
+node(Remarks Ly2dvi)(Author Ly2dvi)(Mi2mu)(Ly2dvi)
+manpageauthor()
+
+nemail(Jan Arne Fagertun)(Jan.A.Fagertun@energy.sintef.no), lurl(http://www.termo.unit.no/mtf/people/janaf/)
+
--- /dev/null
+article(AUTHORS - who did what on GNU LilyPond?)()()
+
+This file lists authors of GNU LilyPond, and what they wrote.
+This list is alphabetically ordered.
+
+itemize(
+it()nemail(Mats Bengtsson)(matsb@s3.kth.se),
+ lurl(http://www.s3.kth.se/~matsb)
+ clef stuff, key stuff, swedish notenames, testing, general
+ comments.
+it()nemail(Eric Bullinger)(eric@aut.ee.ethz.ch),
+ accidental transposition.
+it()nemail(Jan Arne Fagertun)(Jan.A.Fagertun@energy.sintef.no),
+ TeX titling and lytodvi.sh
+it()nemail(Anthony Fok)(foka@debian.org),
+ debian package: debian/*
+it()nemail(Neil Jerram)(nj104@cus.cam.ac.uk).
+ parts of Documentation/Vocab*
+it()Donald Ervin Knuth, lurl(http://www.cs-staff.stanford.edu/~knuth)
+ mf/ital-*.mf (these were taken from the CM fonts)
+it()nemail(Werner Lemberg)(xlwy01@uxp1.hrz.uni-dortmund.de),
+ misc bugfixes, some Beam and Stem code.
+it()nemail(David R. Linn)(drl@vuse.vanderbilt.edu),
+ Mailing list maintenance.
+it()nemail(Han-Wen Nienhuys)(hanwen@cs.uu.nl),
+ lurl(http://www.cs.uu.nl/~hanwen)
+ nl()
+ Main author.
+it()nemail(Jan Nieuwenhuizen)(janneke@gnu.org),
+ lurl(http://www.digicash.com/~jan)
+ nl()
+ Main author
+it()nemail(Alexandre Oliva)(oliva@dcc.unicamp.br),
+ lurl(http://sunsite.unicamp.br/~oliva)
+ testing
+it()nemail(Franc,ois Pinard)(pinard@iro.umontreal.ca),
+ parts of Documentation/Vocab*, started internationalization stuff
+it()nemail(Jeffrey B. Reed)(daboys@bga.com),
+ Windows-NT support.
+it()Shay Rojanski
+ Some mudela source.
+)
+
+
+Your name could be here! If you want to help, then take a look at the
+SMALLISH PROJECTS section of in the file file(TODO). Some do not involve
+coding C++
+
+[And of course we sincerely thank J.S.Bach, F.Schubert, T. Merula and
+W.A.Mozart for their beautiful music]
+
projects / lilypond.git / commitdiff