From 019d6784661b4b653a90257425e600100704d544 Mon Sep 17 00:00:00 2001 From: fred Date: Mon, 10 Aug 1998 22:51:10 +0000 Subject: [PATCH] lilypond-1.0.1 --- Documentation/CodingStyle.yo | 423 +++++++++++++++++++++++++++++++ Documentation/faq.yo | 398 +++++++++++++++++++++++++++++ Documentation/gnu-music.yo | 108 ++++++++ Documentation/man/lilypond.yo | 251 ++++++++++++++++++ Documentation/man/ly2dvi.yo | 199 +++++++++++++++ Documentation/topdocs/AUTHORS.yo | 51 ++++ 6 files changed, 1430 insertions(+) create mode 100644 Documentation/CodingStyle.yo create mode 100644 Documentation/faq.yo create mode 100644 Documentation/gnu-music.yo create mode 100644 Documentation/man/lilypond.yo create mode 100644 Documentation/man/ly2dvi.yo create mode 100644 Documentation/topdocs/AUTHORS.yo diff --git a/Documentation/CodingStyle.yo b/Documentation/CodingStyle.yo new file mode 100644 index 0000000000..fb74fdfc2e --- /dev/null +++ b/Documentation/CodingStyle.yo @@ -0,0 +1,423 @@ +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 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. + + diff --git a/Documentation/faq.yo b/Documentation/faq.yo new file mode 100644 index 0000000000..968fbb6b3f --- /dev/null +++ b/Documentation/faq.yo @@ -0,0 +1,398 @@ +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! + diff --git a/Documentation/gnu-music.yo b/Documentation/gnu-music.yo new file mode 100644 index 0000000000..5e57da7854 --- /dev/null +++ b/Documentation/gnu-music.yo @@ -0,0 +1,108 @@ +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. + diff --git a/Documentation/man/lilypond.yo b/Documentation/man/lilypond.yo new file mode 100644 index 0000000000..c027f6c6f5 --- /dev/null +++ b/Documentation/man/lilypond.yo @@ -0,0 +1,251 @@ +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) +) diff --git a/Documentation/man/ly2dvi.yo b/Documentation/man/ly2dvi.yo new file mode 100644 index 0000000000..d0a0c6dd28 --- /dev/null +++ b/Documentation/man/ly2dvi.yo @@ -0,0 +1,199 @@ +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/) + diff --git a/Documentation/topdocs/AUTHORS.yo b/Documentation/topdocs/AUTHORS.yo new file mode 100644 index 0000000000..b1c6ec64bd --- /dev/null +++ b/Documentation/topdocs/AUTHORS.yo @@ -0,0 +1,51 @@ +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] + -- 2.39.5