From: Han-Wen Nienhuys Date: Thu, 16 Mar 2000 16:33:09 +0000 (+0100) Subject: release: 1.3.35 X-Git-Tag: release/1.3.35 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=fbe603b3f54ca3df39e3778f67085d75c3e97547;p=lilypond.git release: 1.3.35 ====== * Removed Documentation/programmer directory 1.3.34.j --- diff --git a/CHANGES b/CHANGES index 17988e6c44..a64562175a 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,8 @@ +1.3.35 +====== + +* Removed Documentation/programmer directory + 1.3.34.jcn3 =========== @@ -7,18 +12,12 @@ - to change the alignment, use property marginScriptHorizontalAlignment (centred and right alignment require manual padding settings). -1.3.34.jcn2 -=========== - * Print a friendly message if the manual pages failed to build. * Bugfix: dynamicDirection now overrides verticalDirection setting. * Warning messages and nl.po -1.3.34.jcn1 -=========== - * Fixed vertical alignment for all dynamic items and (reluctantly) reinstated old directional behaviour for orphaned dynamics. diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index dd49ab04a3..f1b3fcddf2 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -1,17 +1,18 @@ depth = .. NAME = documentation -SUBDIRS= user programmer bibliography pictures topdocs ntweb misc -STEPMAKE_TEMPLATES=documentation texinfo +SUBDIRS=user bibliography pictures topdocs ntweb misc +STEPMAKE_TEMPLATES=documentation texinfo tex +LOCALSTEPMAKE_TEMPLATES=lilypond mudela README_TOP_FILES=NEWS DEDICATION CHANGES TODO -EXTRA_DIST_FILES = +EXTRA_DIST_FILES= include $(depth)/make/stepmake.make default: local-doc -local-WWW: copy-for-me +local-WWW: copy-for-me $(outdir)/regression-test.ps.gz $(outdir)/regression-test.html copy-for-me: $(foreach a, $(README_TOP_FILES),cp ../$(a) $(outdir)/$(a).txt && ) true diff --git a/Documentation/README-W32.texi b/Documentation/README-W32.texi new file mode 100644 index 0000000000..8abbb88413 --- /dev/null +++ b/Documentation/README-W32.texi @@ -0,0 +1,820 @@ +\input texinfo @c -*-texinfo-*- +@setfilename README-W32.info +@settitle LilyPond on W32 + + +@node Top, , , (dir) + +@chapter LilyPond on W32 + +FIXME: remove yodl refs. + +[FIXME: THIS DOCUMENTED IS OUTDATED] + +No, there's no reason to be concered, Lily should work in +Windows-NT(/95/98?) too. The setup may not be easy or smooth. This +document will help you getting started. + + +@section DISCLAIMER + +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 @strong{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. + +``Ok, thanks for the suggestions. I can't run Linux or I don't want +to run Unix. What can I expect?'' + +@itemize @bullet +@item LilyPond development is moving quite fast, and all developers use Unix. + Newly added features may require some attention to get them to work. +@item LilyPond depends on a number of other packages that usually are + available on Unix boxes, but are not installed by default on Windows. +@end itemize + + +LilyPond will now install/extract in a unix-like tree: +@example + + usr/[local/]bin/ + usr/[local/]share/lilypond/* + +@end example + +etc. + +Lily runs in a the unix-like Cygnus gnu-windows environment; +hopefully Cygnus will adopt the @file{/usr/[local/]} tree too. + +@* +If you really don't want usr/ in your root directory, but rather scatter +your programs and packages all over your harddisk, do something like: +@example + + md lilypond + cd lilypond + unzip ../lilypond-0.1.77.exe.zip + +@end example + +and add @file{lilypond/usr/bin} to your @file{PATH} and +@file{lilypond/usr/share/lilypond} to your @file{LILYINCLUDE}. + + +If you've received a binary release of LilyPond (@file{.exe.zip}), +you may skip the following sections. + + +It can be done! Occasionally, the Cygnus b19.1 cross compiler and +utilities under GNU/Linux are used to make the binary @file{.exe.zip} +releases (some makefile hacking was needed to build this stuff). Jeffrey +Reed tries to keep-up with LilyPond development, and is doing quite +well. His latest release is available on +@uref{http://home.austin.rr.com/jbr/jeff/lilypond/}. + + +I have heard of such tools that think they're probably much smarter than the +packager and thus decide for themselves that they don't need to unpack certain +files (e.g., empty directories such as bin/out). + +To unpack the lilypond sources, you should do something like: @example + + tar zxf releases/lilypond-x.y.z.tar.gz + +@end example + + +If you're familiar with the GNU/Cygnus development package, you may skip +this. + +Don't forget to set +@example + + /start/settings/control-panel/system/environment/system-variables: + GCC_EXEC_PREFIX=/Cygnus/b19/H-i386-cygwin32/lib/gcc-lib/ + MAKE_MODE=UNIX + +@end example + +You want to run bash, while building Lily: +@example + + c:\bash + bash-2.01$ + +@end example + +The install instructions mention something like: +@example + + configure + make + make install + +@end example + +Now for a small UNIX lesson: The current working directory (cwd) is +by default not in your PATH, like it is under DOS (for security reasons). +Check this by looking at the output of: +@example + + echo $PATH + +@end example + +The cwd looks like @code{'::'} or @code{':.'}. If it's not there, you may +add the cwd to your path: +@example + + PATH=$PATH:. + +@end example + +or you must use './' when issuing a command in th cwd, try: +@example + + ./configure + make + +@end example + +My point of reference comes from 15 odd years working with a variety +of @code{UNIX} platforms. I am relatively new to Windows-NT and, even +though I am a card carrying @code{UNIX} bigot, I am excited about the +NT OS. My goals for lilypond are to give back to the Free Software +Foundation a little of what they have given me over the years and to +contribute to the lilypond project by supporting a Windows-NT port. I +hope that someday we can distribute and run lilypond on the NT OS in a +much more native fashion. + +@itemize @bullet + +@item Building lilypond on Windows-NT +@item Maintaining lilypond on Windows-NT +@item Running lilypond on Windows-NT + +@end itemize + + +Currently as stated above lilypond is primarily a @code{UNIX} thing. +The Windows-NT port is based on the @code{UNIX} environment provided by +@uref{http://www.cygnus.com,Cygnus}. Therefore the first step is to +download and install the Cygnus development kit: + +@uref{http://www.cygnus.com/misc/gnu-win32/} + +Please follow the documentation Cygnus has on there web site for +downloading and installing. The important part is that you down load +the entire development kit. I believe it is @file{full.exe}. The +installation will ask you where you want to install it. I will refer +to Cygnus installation directory as @file{/gnuwin32/cygwin-b20}. There +should be a @file{README} file that contains installation instructions. +After the installation is complete you should have a @emph{Cygnus} +shortcut in your @emph{Program} section of your @emph{Start Menu}. This +shortcut is your door to the @code{UNIX} world and I will refer to the +resulting window as a @file{bash} shell. + +The shortcut points to @file{/gnuwin32/cygwin-b20/cygnus.bat}. The +following is my @file{cygnus.bat} file. + +@example + +@@ECHO OFF +rem default environment + +rem GNU cygnus installation + +SET CYGREL=B19.1 +SET MAKE_MODE=unix +SET LOCAL_ROOT=d:\gnuwin32 +SET LOCAL_FS=d:/gnuwin32 +SET LOCAL_DIR=d:/gnuwin32/cygwin-b20 +SET CYGROOT=%LOCAL_ROOT%\cygwin-b20 +SET CYGFS=%LOCAL_FS%/cygwin-b20 +SET TCL_LIBRARY=%CYGROOT%\share\tcl8.0 +rem +rem This was not in the original but is needed by lots of packages +rem +SET BISON_SIMPLE=%CYGFS%/share/bison.simple + +rem +rem I place the cygnus stuff in front of /WINNT +rem + +SET PATH=d:\bin;%LOCAL_ROOT%\bin;%CYGROOT%\H-i586-cygwin32\bin;%PATH% +SET MANPATH=%LOCAL_ROOT%\man;%LOCAL_ROOT%\cygwin-b20\full-man\man +SET INFOPATH=%LOCAL_FS%/cygwin-b20/full-man/info;%LOCAL_FS%/cygwin-b20/info;%LOCAL_DIR%/info + +rem General tools not included with Cygnus Development Kit + +rem CVS + +SET PATH=%PATH%;%LOCAL_ROOT%\cvs-1.9.28\bin +SET INFOPATH=%INFOPATH%;%LOCAL_FS%/cvs-1.9.28/info +SET MANPATH=%MANPATH%;%LOCAL_ROOT%\cvs-1.9.28\man + +rem EMACS + +SET PATH=%PATH%;%LOCAL_ROOT%\emacs-19.34\bin +SET INFOPATH=%INFOPATH%;%LOCAL_FS%/emacs-19.34/info + +rem VIM + +SET VIM=%LOCAL_ROOT%\vim-4.6\doc +SET PATH=%PATH%;%LOCAL_ROOT%\vim-4.6 + +rem TeX + +SET PATH=%PATH%;%LOCAL_ROOT%\texmf\miktex\bin + +rem a2ps + +SET PATH=%PATH%;%LOCAL_ROOT%\a2ps-4.10\bin +SET INFOPATH=%INFOPATH%;%LOCAL_FS%/a2ps-4.10/info +SET MANPATH=%MANPATH%;%LOCAL_ROOT%\a2ps-4.10\man + +rem python + +SET PATH=%PATH%;\Program Files\Python + +rem perl + +SET PATH=%PATH%;\qub + +rem yodl + +uname -sv +bash -login + +@end example + +Please look over this carefully. Be careful with the forward and +backward slash notations. The paths specified were done for good +reasons. Maybe someday we will all be using @code{UNC}. Note the +@code{BISON} entry and the @code{PATH} ordering in particular. Also note +that the generic @file{cygnus.bat} you will be looking at does not +include alot of the packages listed. We will be installing some of +these. + +The installation also suggests that you create a directory @file{/bin} +and copy @file{/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/sh.exe} to +@file{/bin}. The @file{sh.exe} shell provided by Cygnus is a descendant +of the @file{ash} shell. The @file{sh.exe} shell has improved greatly +and is much faster than the @file{bash} shell for script invocations. +So this is my recommendation for post installation steps. From a +@file{bash} shell: + +@itemize @bullet +@item @code{cd /} +@item @code{mkdir bin} +@item @code{cd /bin} +@item @code{cp /gnuwin32/cygwin-b20/H-i586-cygwin32/bin/sh.exe sh.exe} +@item @code{cp /gnuwin32/cygwin-b20/H-i586-cygwin32/bin/bash.exe bash.exe} +@item @code{cd /} +@item @code{mkdir /tmp} +@item @code{chmod a+rwx tmp} +@item @code{mkdir /etc} +@item @code{cd /etc} +@item @code{mkpasswd -l > passwd} +@item @code{mkgroup -l > group} +@end itemize + + +There is also some discussion of how you want to @emph{mount} the Cygnus +development kit. @emph{mount} is a @code{UNIX} term that refers to the +mechanism used to provide a disk resource to the filesystem. Cygnus +supplies a mechinism for @emph{mounting} a filesystem as a @code{DOS} like +resource or a @code{UNIX} like resource. Among other things this +attempts to deal with the text file carriage return line feed on +@code{DOS} versus the line feed on @code{UNIX} and the issue that @code{DOS} +has two file types, text and binary. Where @code{UNIX} deals with a +single streams type. My opinion on this matter currently is to use +binary mounts only. This can be accomplished by: + +@itemize @bullet +@item From a bash shell, umount / +@item mount -b d: / +@end itemize + +If you have other disks that you intend to use for data generated by +cygnus tools you will have to mount those devices with the @emph{-b} +switch. + + +@uref{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/egcs.html} + +Cygnus now distributes the ecgs compiler with cygwin-b20. + + +@uref{http://www.gnu.org/order/ftp.html} + +Considering the origin of the major contributors of lilypond, this is a +must. However before we actually do a @strong{GNU} build we have to +discuss some caveats of the Windows-NT OS in particular the naming of +executable files. @code{Windows-NT} uses a .exe extension where @code{UNIX} +does not use an extension. This causes a problem during the +installation portion of a @strong{GNU} build. The following script can be +used to help alleviate this problem. + +@example + +#!/bin/sh + +realinstall=/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/install.exe +args='' +while [ $# -ne 0 ] +do + case $1 in + -*) args="$args $1" + ;; + + *) if [ -f $1.exe ]; then + args="$args $1.exe" + else + args="$args $1" + fi + ;; + esac + shift +done + +$realinstall $args + +@end example + +I place this in script @file{~/bin}. The LilyPond configure, build, +and install process handles this with it's own install script. In +addition there are patches to the cygnus install command that also +deals with this problem. Having said that, here is how one +might build the @emph{gettext} package. + +@itemize @bullet +@item download the package from one of the ftp sites. +@item From a bash shell, cd ~/usr/src. +@item tar zxf gettext-0.10.tar.gz +@item cd gettext-0.10 +@item ./configure --prefix=$CYGFS/H-i586-cygwin32 +@item make +@item make install +@end itemize + + +@uref{http://www.gnu.org/order/ftp.html} + +Following the instructions for @emph{gettext} package to download, build, +and install the @emph{groff} package. + + +@uref{http://www.python.org} + +Python is the scripting language of choice for a lilypond build. +There is a native @code{Windows-NT} self extracting binary distribution +available. I recommend installing Python in a directory that does +@strong{not} have spaces. And then place it in the bash shell path by +editing $CYGFS/cygnus.bat. + + +@uref{http://www.cpan.org} + +I believe perl is used in some legacy scripts to date. There is a +native @code{Windows-NT} self extracting binary distribution available. +I recommend installing Perl in a directory that does @strong{not} have +spaces. And then place it in the bash shell path by editing +$CYGFS/cygnus.bat. + +The development methodology of @emph{LilyPond} relies on a the following +directory structure: + + +@example + +$HOME/usr/src/ + |-releases/ + |-patches/ + |-test/ + +@end example + +@table @samp + +@item releases/ Downloaded and generated releases live here. For +example @file{lilypond-1.1.17.tar.gz}. + +@item patches/ Downloaded and generated patches live here. For +example @file{lilypond-1.1.17.diff.gz}. + +@item test/ This directory is used to generate releases and patches. + +@end table + +I strongly recommend using this file structure to build @emph{yodl} and +@emph{lilypond}. + +@itemize @bullet +@item download the package from +@uref{http://www.xs4all.nl/~jantien/yodl/} to +@file{$HOME/usr/src/releases}. +@item From a bash shell, cd @file{$HOME/usr/src}. +@item tar zxf releases/yodl-@emph{}.tar.gz +@item cd yodl-@emph{} +@item ./configure --prefix=/gnuwin32/yodl-@emph{} --srcdir=. +Since @emph{yodl} is under development I choose to install it in a +version rooted directory. This allows me to test newly released +versions without losing a known working version. + +@item make +@item make install +@item place it in the bash shell path by editing $CYGFS/cygnus.bat. +For example: +@example +rem yodl + +SET PATH=%PATH%;%LOCAL_ROOT%\yodl-1.31.7\bin + + +@end example + +@end itemize + + + +GUILE, GNU's Ubiquitous Intelligent Language for Extension, is a +library that implements the Scheme language plus various convenient +facilities. It's designed so that you can link it into an application +or utility to make it extensible. GNU's plan is to link this library +into all GNU programs that call for extensibility. + +@itemize @bullet +@item download guile-1.3 patch from +@uref{http://home.austin.rr.com/jbr/jeff/lilypond/guile.patch} and save it +to @file{/tmp/guile.patch}. +@item download guile-1.3 from one of GNU's ftp sites. +@item From a bash shell, tar zxf guile-1.3.tar.gz +@item cd guile-1.3 +@item patch -p2 < /tmp/guile.patch +@item LD=/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/ld \ @* + ./configure --prefix=$CYGFS/H-i586-cygwin32 +@item make sure bin_PROGRAMS macro in libguile/Makefile does @emph{not} have the +.exe extension during the build +@item make +@item make sure bin_PROGRAMS in libguile/Makefile @emph{does} have the +.exe extension during the install. Yuck. +@item make install +@end itemize + + +@itemize @bullet +@item download the package from +@uref{http://www.cs.uu.nl/people/hanwen/lilypond/} to +@file{$HOME/usr/src/releases}. +@item From a bash shell, cd @file{$HOME/usr/src}. +@item tar zxf releases/lilypond-@emph{}.tar.gz +@item cd lilypond-@emph{} +@item ./configure --prefix=/gnuwin32/lilypond-@emph{} \ @* + --srcdir=. @* +Since @emph{lilypond} is under development I choose to install it in a +version rooted directory. This allows me to test newly released +versions without losing a known working version. +@item make +@item make install +@item place it in the bash shell path by editing $CYGFS/cygnus.bat. +For example: +@example +rem lilypond + +SET PATH=%PATH%;%LOCAL_ROOT%\lilypond-1.1.17\bin + + +@end example + +@end itemize + + +If you have built @emph{lilypond} on @code{Windows-NT} using the directory + and the process described +in section FIXME, then you are ready to maintain +@emph{lilypond}. It can not be that easy!? Well, there is one caveat. +Currently to use the @file{stepmake/bin/release.py} and +@file{stepmake/bin/package-diff.py} scripts you need to obtain/build a +version of @emph{python} that was built with @strong{Cygnus} development kit. +The process I used is as follows: + +@itemize @bullet +@item obtain python source from @uref{http://www.python.org} +@item tar zxf /tmp/python-@emph{}.tar.gz +@item cd python-@emph{} +@item configure --prefix=/gnuwin32/Python-@emph{} +@item edit toplevel @file{Makefile} @code{EXE} macro so it reads @code{EXE=.exe} +@item make +@item make install +@item place it in the bash shell path by editing $CYGFS/cygnus.bat. +For example: +@example +rem python + +SET PATH=%PATH%;%LOCAL_ROOT%\python-1.5.1\bin + + +@end example + +@end itemize + +I choose to build @emph{lilypond} with the standard @code{Windows-NT} +@emph{python} and use the @strong{Cygnus} version for using the release +scripts. This way I can make sure the @code{Windows-NT} @emph{python} +version is able to build @emph{lilypond}. Currently there are several +issues with the release scripts. Using @code{os.link} and +@code{os.system(set -x;...)} are to name a few. + +To generate a new release and patch you must use the directory +. And follow the +instructions found in @file{PATCH.txt}. Editing +@file{Documentation/AUTHORS.yo}, @file{VERSION}, and @file{NEWS} is also +required. When my edits are complete and tested I: + +@itemize @bullet +@item Edit @file{config.make} and change @emph{python} path to the +@strong{Cygnus} version: @code{PYTHON=/gnuwin32/Python-1.5.1/bin/python}. +@item make release +@end itemize + +The new release is placed in @file{releases} directory and the patch is +placed in the @file{patches} directory. I email the new patch to +@email{gnu-music-discuss@@gnu.org}. More than one patch a day can be +generated by: + +@itemize @bullet +@item cd $HOME/usr/src +@item tar zxf releases/lilypond-@emph{}.@emph{} +@item use your normal configure +@item make edits +@item Change @file{VERSION} to increment @emph{} +@item Change @file{NEWS} +@item make release +@end itemize + + +We are now distributing a formated binary distribution for +Windows-NT. Please refer to +@uref{http://home.austin.rr.com/jbr/jeff/lilypond/} for current news, +download, installation, and running information. + +Jeffrey B. Reed @email{daboys@@austin.rr.com} + +@section RUNNING LILYPOND -- by Dominique Cretel + +You may want to refer to section FIXME, for more current +information about downloading, installing, and running the Windows-NT +binary distribution. + +@enumerate i +@item First, I have download tha 0.1.64 version of LilyPond music software. + +@item Then I extract it in a temp directory, and I move the directory +"lilypond-0.1.64" to the root directory of my D drive. + +@item I go to the D:\Lilypond-0.1.64\tex directory to modify the +lilyponddefs.tex file (lines 75 and 84), and comment all +cmbx15 ans cmbx14, and replace them by cmbx12. + +@item build a command file like this: +Note: I use MiKTeX to process the tex file generated. + +@example + +---begin ly2dvi.bat +echo off +set ver=0.1.64 +set path=%path%;d:\lilypond-%ver%\bin +lilypond -I d:\lilypond-%ver%\init %1 +rem *** pause + +set path=c:\texmf\miktex\bin;%path% +set TEXINPUTS=%TEXINPUTS%;d:\lilypond-%ver%\tex +set MFINPUTS=%MFINPUTS%;d:\lilypond-%ver%\mf +tex %1.tex +rem *** pause + +dvips %1.dvi +rem *** pause + +set path=%path%;d:\gstools\gsview +gsview32 %1.ps +---end ly2dvi.bat + +@end example + +@item execute lilypond by doing: +@example + +ly2ps silly + +@end example + +@end enumerate + +Note: +@* +You'll better have to put the SET commands lines in a separate command +file to avoid consumming each time environnment ressources. + +Bye,@* +Dominique Cretel @email{dominique.cretel@@cfwb.be} + +@section PROBLEMS AND ANWSWERS + +This is all to confusing. I have: +@enumerate i +@item downloaded @file{/tmp/lilypond-0.1.78.tar.gz} +@item @example + + cd ~/usr/src + +@end example + +@item @example + + tar zxf /tmp/lilypond-0.1.78.tar.gz + +@end example + +@item @example + + ./configure --prefix=/users/jeff/lilypond-0.1.78 \--enable-tex-prefix=/users/jeff/lilypond-0.1.78/texmf \--enable-tex-dir=/users/jeff/lilypond-0.1.78/texmf/tex \--enable-mf-dir=/users/jeff/lilypond-0.1.78/texmf/mf + +@end example + +@item @example + + make + +@end example + +@item @example + + make install + +@end example + +@end enumerate + +I did have a problem with lilypond.info. And I will look into this +further. After mending lilypond.info issue, it compiled and install +with no problems. + +I have 64 Meg of physical memory and 64 Meg of swap. Actually I need +to increase the swap space. If a memory problem is occuring it most +likely is during the link process of lilypond. There is a boat load +of objects to link. + +Jan the mount -b stuff is confussing to me. I have the entire system +mounted _without_ -b and only use -b on certain paths for programs +that create binary files that do not use O_BINARY open option. By the +way the midi file open is one of these cases, I need to look into +that. I have had no problems with this methodology. + + +The windows multiroot filesystem is an utterly broken concept. Please +do everything on one (urg) drive, C:. + +@example + +> configure +> creating cache ./config.cache +> [..] +> creating config.make +> creating config.hh +> cd: lstat /d failed + +@end example + +Ok, this looks like another stupid windows problem. +You're working on 'drive D:', right? + +I can think of some solutions, but i don't know if they work; +i just had to do some work in windows some time ago. If you +have problems with this, please ask @email{gnu-win32@@cygnus.com}. +I'll start with the simplest: +@itemize @bullet + @item do everything on drive C:, or + @item explicitely mount drive d:, work from there: + @example + + mkdir -p /mnt/d + mount d: /mnt/d + cd /mnt/d/lilypond-x.y.z/ + +@end example + + @item make d:/ the root of cygnus, in cmd.exe/command.exe do: + @example + + umount / + mount d: / + +@end example + +@end itemize + + +> - First I have installed Python (for win32) "Pyth151.exe" and "Configure +@* +> don't find it. I had to put it in the path for configure find it? +@* + +Yes, of course. It should be possible to have different versions of tools +installed (e.g. perl 4 and perl 5). The best way to tell people (or tools +like configure) which one to use is to put it in the path? + +Another small unix lesson: Where under dos each program installs itself +into a nice directory +@example + + c:\DosProgram\* + +@end example + +under unix, installation is handled centrally. Executables go in +@file{/usr/bin} (or @file{/usr/local/bin}), and are always in your path. + + +@example + +> 4. make -C lily don't work. I get an error (see below). I get several +> object files in the ./lily/out directory (34 files: 17 *.dep, 16 *.o, +> and 1 *.hh): +> [...] +> include/engraver-group.hh:35: virtual memory exhausted +> make: *** [out/bar-grav.o] Error 1 +> bash-2.01$ + + +@end example + +Ok, so everything works now, there's only some error with one of the +source files. Lets see which one (and now the cc's now why they're +reading this :-) + +It looks like you've run out of memory. You should compile without +optimisation, gcc/egcs need a lot of memory for optimising. +Reconfigure without optimisation: +@example + + configure --disable-optimise + +@end example + +or edit @file{config.make}: +@example + + ## USER_CXXFLAGS = -g # -O no optimise! + USER_CXXFLAGS = -g + +@end example + +There are some other things to look at: how much RAM do you have +(please say something > 8Mb :-)? Although it might be an egcs bug, +you should have a look at the size of your swap file. +For an US version of windows, you should find it here: +@example + + /start/settings/control-panel/system/performance/virtual-memory + +@end example + +you see, amongst others, these entries: +@example + + paging file size for selected drive: + + space-available: xx + initial-size: xx + maximum-size: xx + + total paging file size for all drives + + currently allocated: xx + +@end example + +Try to set: +@example + + initial-size: 64 + maximum-size: 128 + +@end example + +Make sure that: +@itemize @bullet +@item maximum-size >= 128 Mb +@item urrently-allocated + space-available >= 128 Mb +@end itemize + + +@bye diff --git a/Documentation/hacking.texi b/Documentation/hacking.texi new file mode 100644 index 0000000000..da36f2f0ef --- /dev/null +++ b/Documentation/hacking.texi @@ -0,0 +1,856 @@ +\input texinfo @c -*-texinfo-*- +@setfilename internals.info +@settitle LilyPond internals + +@node Top, LilyPond internals, (dir), (dir) +@top + + +@menu +* LilyPond internals:: +* Overview:: +* mudela:: +* Request_engraver:: +* Graphic elements:: +* Score elements:: +* Items:: +* Spanners:: +* Future work:: +* Coding standards:: +* Making patches:: + +@end menu + +@node LilyPond internals, , Top, Top +@menu +* Overview:: Overview +* mudela:: mudela +* Request_engraver:: Request_engraver +@end menu + + +@chapter Getting involved + +Please help us make LilyPond a better program. You can help LilyPond in +several ways. Not all tasks requiring programming or understanding the +full source code. You can write to the mailing list +(@email{gnu-music-discuss@@gnu.org} for more information) + +@unnumberedsubsec Users + +Mutopia needs your help. The mutopia project is a collection of public +domain sheet music. You can help the project by entering music and +submitting. Point your browser to the +@uref{http://sca.uwaterloo.ca/Mutopia, Mutopia webpage} + +@unnumberedsubsec Font designers + +Our set of glyphs (the Feta font) is far from complete. If you know a +little MetaFont you can contribute a glyph + +@unnumberedsubsec Writers + +The documentation of LilyPond and related utilities needs a lot of work. + +@unnumberedsubsec Translators + +LilyPond is completely ready for internationalized messages, but there +are only three translations so far. + +@unnumberedsubsec Hackers + +There are lots of possibilities of improving the program itself. There are +both small projects and big ones. Most of them are listed in the TODO +file. A interesting and very big project is writing a GUI frontend to +LilyPond. + + +@unnumberedsubsec Website designers + +The current website for LilyPond is neat and simple, but it is not very +pretty. We would like to have a website with pretty pictures, one that +looks appealing to new users. + + +@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, Top, Top +@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, Top +@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, , mudela, Top +@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 Graphic elements, , , Top +@section Graphic elements + + +Music notation is composed of a sets of interrelated glyphs. In +Lilypond every glyph usually is represented by one object, a so-called +Graphic Object. The primary relations between graphic objects involve +positions: + +@itemize +@item consecutive notes are printed left to right, grouped in a staff +@item simultaneous notes are horizontally aligned (internally grouped in +a paper column). +@item the staccato mark is horizontally centered on the note it applies +to. +@end itemize + +The abstract encoding of such relations is done with the concept +@dfn{reference point}. The reference point (in X direction) of the +staccato mark is the note it applies to. The (X) position of the +staccato mark is stored relative to the position of the note head. This +means that the staccato will always maintain a fixed offset wrt to the +note head, whereever the head is moved to. + +In the same vein, all notes on a staff have their Y positions stored +relative to an abstract object called Axis_group_spanner. If the +Axis_group_spanner of one staff is moved, the absolute Y positions of +all objects in that spanner change along, in effect causing the staff +and all its contents to move as a whole. + +Each graphic object stores a pointer and an relative offset for each +direction: one for the X-axis, one for the Y-axis. For example, the X +parent of a Note_head usually is a Note_column. The X parent of a +Note_column usually is either a Collision or a Paper_column. The X +parent of a Collision usually is a Paper_column. If the Collision +moves, all Note_heads that have that Collision as parent also move, but +the absolute position of the Paper_column does not change. + +To build a graphical score with Graphic_elements, conceptually, one +needs to have one Root object (in Lilypond: Line_of_score), and +recursively attach objects to the Root. However, due to the nature +of the context selection mechanisms, it turns out to be more +advantageous to construct the tree the other way around: first small +trees (note heads, barlines etc.) are created, and these are +subsequently composed into larger trees, which are finally hung on a +Paper_column (in X direction) or Line_of_score (in Y direction). + +The structure of the X,Y parent relations are determined by the +engravers and notation contexts: + +The most important X-axis parent relation depends on the timing: notes +that come earlier are attached to Paper_column that will be positioned +more to the left. + +The most important Y-axis relation depends on containment of contexts: +notes (created in a Thread or Voice context) are put in the staff where +the originating context lives in. + +Graphical_axis_groups are special graphic objects, that are designed to +function as a parent. The size of a Graphical_axis_groups group is the +union of its children. + +@node Score elements, , , Top + +Besides relative positions there are lots of other relations between +elements. Lilypond does not contain other specialized relation +management (Like the relative positioning code). In stead, objects can +be connected through dependencies, which sets the order in which objects +are to be processed. + +Example: the direction of a beamed stem should equal the direction of +the beam. When the stem is a added to the beam, a dependency on the +beam is set in the stem: this means that @code{Beam::do_pre_processing +()} (which does various direction related things) will be called before +@code{Stem::do_pre_processing ()}. + +The code that manages dependencies resides in the class +@code{Score_element}, a derived class of @code{Graphical_element}. The +bulk of the code handles line breaking related issues. + +To sketch the problems with line breaking: suppose a slur spans a line +break, +@example + +c4( c'''' c | \break d d )d + +@end example +In this case, the slur will appear as two parts, the first part spanning +the first three notes (the @code{c}s), the second spanning the last +three (the @code{d}s). Within Lilypond this is modeled as breaking the +slur in parts: from the Original slur, two new clones of the old slur +are made. Initially both clones depend on the six notes. After the +hairy code in Score_element, Spanner and Item which does substitutions +in sets of dependencies, the first clone depends on the first three +notes, the second on the last three. + +The major derived classes of Score_element are Item and Spanner. +An item has one horizontal position. A spanner hangs on two items. + +@node Items, , , Top +@section Items + + + +An item is a score element that is associated with only one +Paper_column. Examples are note heads, clefs, sup and superscripts, etc. +Item is a derived class of Score_element. + +The shape of an item is known before the break calculations, and line +spacing depends on the size of items: very wide items need more space +than very small ones. + +An additional complication is the behavior of items at linebreaks. For +example, when you do a time signature change, you get only one symbol. +If it occurs at a linebreak, the new time signature must be printed both +before and after the linebreak. Other `breakable symbols' such as +clefs, and bar lines also exhibit this behavior. + +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. To support this, +breakable items are generated in the three versions: original +(unbroken), left (before line break) and right (after line break). +During the line spacing, these versions are used to try how the spacing +of a line works out. + +Once the definitive spacing is determined, dependencies (and various +other pointers) are substituted such that all dependencies point at the +active items: either they point at the original, or they point at left +and right. + +@node Spanners, , , Top +@section Spanners + +Spanners are symbols that are of variable shape, eg. Slurs, beams, etc. +Spanners is a derived class of Score_element. + +The final shape can only be determined after the line breaking process. +All spanners are spanned on two items, called the left and right +boundary item. The X reference point is the left boundary item. + + +@node Future work, , , Top +@section Future work + +There are plans to unify Spanner and Item, so there will no longer be +such a clear distinction between the two. Right now, Score_elements are +always either Item or either Spanner. + +Most of the properties of a graphic object are now member variables of +the classes involved. To offer configurability, we want to move these +variables to scheme (GUILE) variables, and no longer use C++ code to +calculate them, but use Scheme functions. + +@node Coding standards, , , Top + +@chapter CodingStyle - standards while programming for GNU +LilyPond + +Functions and methods do not return errorcodes. + + +@unnumberedsubsec Languages + +C++ and Python are preferred. Perl is not. Python code should use an +indent of 8, using TAB characters. + +@unnumberedsubsec Filenames + +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 + +Standard GNU coding style is used. 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. + +The hungarian notation is to be used when variables are not declared +near usage (mostly in member variables and functions). + +@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. + +@node Making patches, , , Top + + +@unnumberedsec name + + +PATCHES - track and distribute your code changes + +This page documents how to distribute your changes to GNU lilypond + +We would like to have unified context diffs with full pathnames. A +script automating supplied with Lily. + +Distributing a change normally goes like this: + +@itemize @bullet +@item make your fix/add your code +@item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi +@item generate a patch, +@item e-mail your patch to one of the mailing lists + gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org +@end itemize + +Please do not send entire files, even if the patch is bigger than the +original. A patch makes it clear what is changed, and it won't +overwrite previous (not yet released) changes. + +@unnumberedsec Generating a patch + +Simple version: run + +@example + make -C lilypond-x.y.z/ distclean + make -C lilypond-x.y.z.NEW/ distclean + diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/ +@end example + +Complicated (but automated) version: + +In @file{VERSION}, set MY_PATCH_LEVEL: + +@example + + VERSION: + ... + MY_PATCH_LEVEL=jcn1 + +@end example + +In @file{CHANGES}, enter a summary of changes: + +@example + pl 0.1.73.jcn1 + - added PATCHES.texi +@end example + +Then, from the top of Lily's source tree, type + +@example + make release +@end example + +These handy python scripts assume a directory structure which looks +like: + +@example + + lilypond -> lilypond-x.y.z # symlink to development directory + lilypond-x.y.z/ # current development + patches/ # patches between different releases + releases/ # .tar.gz releases + +@end example + +(Some scripts also assume this lives in @file{$HOME/usr/src}). + + +@unnumberedsec Applying patches + + +If you're following LilyPond development regularly, you probably want to +download just the patch for each subsequent release. +After downloading the patch (into the patches directory, of course), simply +apply it: + +@example + + gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E + +@end example + +and don't forget to make automatically generated files: + +@example + + autoconf footnote(patches don't include automatically generated files, + i.e. file(configure) and files generated by file(configure).) + + configure + +@end example + + +@bye + + diff --git a/Documentation/index.texi b/Documentation/index.texi index 023b144077..d3ee87f0cd 100644 --- a/Documentation/index.texi +++ b/Documentation/index.texi @@ -6,7 +6,7 @@ @top -@unnumberedsubsec Info +@unnumberedsubsec General information @itemize @bullet @item @uref{DEDICATION.txt,Dedication} @@ -17,8 +17,6 @@ @item @uref{faq.html,FAQ: Frequently asked questions}, with answers @end itemize - - @unnumberedsubsec Manuals @itemize @bullet @@ -29,17 +27,12 @@ terms}, includes translations. Also available in @uref{../user/out-www/glossary @item @uref{../user/out-www/mudela-book.html,mudela-book}, a tool for integrating text and music in LaTeX and texinfo; also available in @uref{../user/out-www/mudela-book.ps.gz,Postscript} -@item @uref{ly2dvi.html,ly2dvi} manual. Ly2dvi does page layout for -LilyPond prints -@item @uref{midi2ly.html,midi2ly} manual. midi2ly converts MIDI files to -LilyPond input -@item @uref{../programmer/out-www/regression-test.html, LilyPond test document} -@end itemize - - -@unnumberedsubsec Status - -@itemize @bullet +@item @uref{../user/out-www/ly2dvi.html,ly2dvi} does page layout for +LilyPond printout. +@item @uref{../user/out-www/midi2ly.html,midi2ly} +converts MIDI files to LilyPond input +@item @uref{regression-test.html, LilyPond test document} +Also available in @uref{regression-test.ps.gz,Postscript} @end itemize @@ -50,8 +43,6 @@ LilyPond input @item @uref{../pictures/out-www/lelie-icon.png, logo} in small size @end itemize - - @unnumberedsubsec Literature @itemize @bullet @@ -68,9 +59,13 @@ by computer}. @end itemize -@unnumberedsubsec Miscellaneous texts +@unnumberedsubsec Background information + + @itemize @bullet +@item @uref{hacking.html,Internals} details of the implementation +@item @uref{README-W32.html,Compiling and running on Windows32} @item @uref{../misc/out-www/CHANGES-0.0.txt, Change logs from 0.0 till 0.1 } @item @uref{../misc/out-www/CHANGES-0.1.txt, Change logs from 0.1 till 1.0 } @item @uref{../misc/out-www/CHANGES-1.0.txt, Change logs from 1.0 till 1.1 } @@ -82,7 +77,7 @@ changes)} changes)} @item @uref{../misc/out-www/ANNOUNCE-1.2.txt, Announcement of 1.2 (includes summary of changes)} @item @uref{../misc/out-www/AIMS.txt, Why LilyPond?} -pp@item @uref{../misc/out-www/interview.txt, Answers} to the Brave GNU world standard questions. +@item @uref{../misc/out-www/interview.txt, Answers} to the Brave GNU world standard questions. @end itemize diff --git a/Documentation/ly2dvi.texi b/Documentation/ly2dvi.texi deleted file mode 100644 index d7cf664d12..0000000000 --- a/Documentation/ly2dvi.texi +++ /dev/null @@ -1,260 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ly2dvi.info -@settitle ly2dvi - -@chapter Ly2dvi - -@section DESCRIPTION -ly2dvi is a Python 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. - -The majority of this utility came from a bourne script written by Jan -Arne Fagertun name @file{ly2dvi}. - -@section SYNOPSIS - - ly2dvi [options] inputfile[.ly] [....] - - -@section OPTIONS - -@table @samp -@item -D,--debug - Set debug mode. There are two levels - in level one some debug - info is written, in level two the command @strong{set -x} is run, which - echoes every command in the ly2dvi script. -@item -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@}} -@item -H,--Heigth= - Set paper heigth (points). Used together with width and LaTeX name of - papersize in case of papersize unknown to ly2dvi. -@item -K,--keeplilypond - Keep LilyPond output after the run. -@item -L,--landscape - Set landscape orientation - portrait is the default. - (@strong{-L} produces @code{\usepackage[landscape]@{article@}}) -@item -N,--nonumber - Switch off page numbering. -@item -O,--orientation= - Set orientation landscape - obsolete, use @strong{-L} instead. -@item -P,--postscript - In addition to the DVI file, also Generate a postsript file. -@item -W,--Width= - Set paper width (points). Used together with heigth and LaTeX name of - papersize in case of papersize unknown to ly2dvi. -@item -d,--dependencies - Tell lilypond to make dependencies file. -@item -h,--help - Print help. -@item -k,--keeply2dvi - Keep the LaTeX file after the run. -@item -l,--language= - Specify LaTeX language. - (@strong{-l norsk} produces @code{\usepackage[norsk]@{babel@}}). -@item -o,--output= - Set output directory. -@item -p,--papersize= - Specify papersize. - (@strong{-p a4} produces @code{\usepackage[a4paper]@{article@}}) -@item -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. -@end table - - -@section Features - -ly2dvi responds to several parameters specified in the mudela -file. They are overridden by corresponding command line options. - -@table @samp -@item language=""; - Specify LaTeX language -@item latexheaders=""; - Specify additional LaTeX headers file -@item orientation=""; - Set orientation. -@item paperlinewidth=""; - Specify the width (pt, mm or cm) of the printed lines. -@item papersize=""; - Specify name of papersize. -@end table - -@section Environment - -@table @samp -@item LILYPONDPREFIX - Sets the root directory of the LilyPond installation -@item LILYINCLUDE - Additional directories for input files. -@item TMP - Temporary directory name. Default is /tmp -@end table - -@section 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: - -@table @samp -@item title - The title of the music. Centered on top of the first page. -@item subtitle - Subtitle, centered below the title. -@item poet - Name of the poet, leftflushed below the below subtitle. -@item composer - Name of the composer, rightflushed below the subtitle. -@item metre - Meter string, leftflushed below the below poet. -@item opus - Name of the opus, rightflushed below the below composer. -@item arranger - Name of the arranger, rightflushed below the opus. -@item instrument - Name of the instrument, centered below the arranger -@item piece - Name of the piece, leftflushed below the instrument -@end table - -@file{$LILYPONDPREFIX/share/.lilyrc $HOME/.lilyrc ./.lilyrc} are files -to set up default running conditions. On Windows OS initialization -files are named @file{_lilyrc}. The file syntax is as follows: - -@example -VARIABLE-NAME=VALUE -@end example - - -Where @strong{VARIABLE-NAME} is the name of the variable documented below -and @strong{VALUE} is either a string, a 1, or a 0. All files are parsed, -in the shown sequence. In the current version the following are -allowed: - -@table @samp -@item DEBUG=value -This turns off (default) or on the debug capabilities. Possible -values are 0 (off) and 1 (on). -@item DEPENDENCIES=value -This turns off (default) or on the ability to generate a Makefile -dependency list. Possible values are 0 (off) and 1 (on). -@item KEEPLILYPOND=value -This turns off (default) or on the ability to keep the log file -associated with the LilyPond job. Possible values are 0 (off) and 1 -(on). -@item KEEPLY2DVI=value -This turns off (default) or on the ability to keep the temporary files -that are generated by the ly2dvi job. Possible values are 0 (off) and -1 (on) -@item LANGUAGE=value -Specify LaTeX language. Possible value is a valid LaTeX language. -@item LATEXHF=value -Specify additional LaTeX headers file. Possible value is a file -specification. -@item LILYINCLUDE=value -Additional directories for input files. Possible value is a delimited -directory path list. -@item LILYPONDPREFIX=value -This defines the LilyPond root directory. Possible value is a valid -directory specification to the LilyPond distribution location. -@item NONUMBER=value -This turns off (default) or on the page numbering capability. -Possible values are 0 (page numbering enabled) and 1 (page numbering -disabled). -@item ORIENTATION=value -This sets the image orientation. Possible values are -portrait (default) and landscape. -@item OUTPUTDIR=value -This defines the directory where the resultant files will be -generated. Possible value is a valid directory specification. -Default is the current working directory. -@item PAPERSIZE=value -This defines the papersize the image will be sized to fit. Possible -values are a0, a1, a2, a3, a4 (default), a5, a6, a7, a8, a9, a10, b0, -b1, b2, b3, b4, b5, archA, archB, archC, archD, archE, flsa, flse, -halfletter, ledger, legal, letter, or note. -@item PHEIGHT=value -Specify paperheight (points - an inch is 72.27, a cm is 28.453 points). -@item POSTSCRIPT=value -This turns off (default) or on the capability of additionally -generating a postscript file. Possible values are 0 (off) and 1 (on). -@item PWIDTH=value -Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points). -@item SEPARATE=value -This turns off (default) or on the capability of generating multiple -dvi and postscript files from multiple source files. The default is -to generate a concatenation of the source files. Possible values are -0 (single file) and 1 (separate files). -@item TMP=value -This defines the emporary directory. Actually this is not used at the -present. Possible value is a valid directory specification that is -writable to the user. -@end table - -@section Initialization Sequence -The initialization process reads inputs for several sources. Below is -a list of priorities for lowest to hightest proirity. - -@itemize @bullet -@item Program's defaults -@item Values found in LilyPond output file -@item Environment variables -@item $LILYPONDPREFIX/share/lilypond/.lilyrc -@item $HOME/.lilyrc -@item ./.lilyrc -@item command line options -@end itemize - -Note that this differs slightly from the original bourne shell -version. - -@section See Also - -lilypond(1), tex(1), latex(1) - -@section Bugs - -If you have found a bug, you should send a bugreport. - -@itemize @bullet -@item Send a copy of the input which causes the error. -@item Send a description of the platform you use. -@item Send a description of the LilyPond and ly2dvi version you use. -@item Send a description of the bug itself. -@item Send it to @email{bug-gnu-music@@gnu.org} (you don't have to subscribe - to this mailinglist). -@end itemize - -@section 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 - -@section Authors -Python Version author: -@email{daboys@@austin.rr.com, Jeffrey B. Reed}, -@uref{http://home.austin.rr.com/jbr/jeff/lilypond/} - -Original bourne shell version author: -@email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun}, -@uref{http://www.termo.unit.no/mtf/people/janaf/} - - - - diff --git a/Documentation/midi2ly.texi b/Documentation/midi2ly.texi deleted file mode 100644 index 7a4609d436..0000000000 --- a/Documentation/midi2ly.texi +++ /dev/null @@ -1,46 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename midi2ly.info -@settitle midi2ly - - -@chapter midi2ly - -@section DESCRIPTION -midi2ly translates a MIDI input file to Mudela (GNU LilyPond source -format). midi2ly is part of the GNU LilyPond music typesetting package. - - midi2ly [options] midi-file - -@section OPTIONS - -@table @samp -@item -b, --no-quantify, - Write exact durations, e.g.: `a4*385/384'. -@item -D, --debug, - Print lots of debugging stuff. -@item -h, --help, - Show a summary of usage. -@item -I, --include=@file{DIR}, - Add DIR to search path. -@item -k, --key=ACC[:MINOR], - Set default key. ACC > 0 sets number of sharps; ACC < 0 sets number - of flats. A minor key is indicated by ":1". -@item -n, --no-silly, - Assume no plets or double dots, assume smallest (reciprocal) duration 16. -@item -o, --output=@file{FILE}, - Set @file{FILE} as default output. -@item -p, --no-plets, - Assume no plets. -@item -q, --quiet, - Be quiet. -@item -s, --smallest=N, - Assume no shorter (reciprocal) durations than N. -@item -v, --verbose, - Be verbose. -@item -w, --warranty, - Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!) -@item -x, --no-double-dots, - Assume no double dotted notes. -@end table - -@bye diff --git a/Documentation/programmer/GNUmakefile b/Documentation/programmer/GNUmakefile deleted file mode 100644 index d54746320a..0000000000 --- a/Documentation/programmer/GNUmakefile +++ /dev/null @@ -1,36 +0,0 @@ -# Documentation/tex/Makefile - -depth=../.. - -TEX_FILES = $(wildcard *.tex) -DOC_FILES = $(wildcard *.doc) -DVI_FILES = $(addprefix $(outdir)/,$(DOC_FILES:.doc=.dvi) $(TELY_FILES:.tely=.dvi)) - -OUTTEX_FILES = $(addprefix $(outdir)/, $(TEX_FILES)) -OUTDOC_FILES = $(addprefix $(outdir)/, $(DOC_FILES)) - -EXTRA_DIST_FILES= $(DOC_FILES) $(TEX_FILES) $(wildcard *.sty) -HTML_FILES = $(addprefix $(outdir)/, $(TEXI_FILES:.texi=.html) $(TELY_FILES:.tely=.html)) -PS_FILES = $(DVI_FILES:.dvi=.ps) - -STEPMAKE_TEMPLATES=tex documentation texinfo -LOCALSTEPMAKE_TEMPLATES=lilypond mudela - -export BIBINPUTS:=$(shell pwd)//$(PATHSEP)$(BIBINPUTS) -include $(depth)/make/stepmake.make - -dvi: $(DVI_FILES) - -ps: $(PS_FILES) - -# urg -default: - - -localclean: - rm -f fonts.aux fonts.log feta*.tfm feta*.*pk - -local-WWW: $(HTML_FILES) $(addsuffix .gz, $(PS_FILES)) - $(PYTHON) $(step-bindir)/ls-latex.py --title 'Hacker documentation' \ - $(DOC_FILES) $(TEXI_FILES) $(TELY_FILES) \ - | sed "s!$(outdir)/!!g" > $(outdir)/index.html diff --git a/Documentation/programmer/README-W32.texi b/Documentation/programmer/README-W32.texi deleted file mode 100644 index 8abbb88413..0000000000 --- a/Documentation/programmer/README-W32.texi +++ /dev/null @@ -1,820 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename README-W32.info -@settitle LilyPond on W32 - - -@node Top, , , (dir) - -@chapter LilyPond on W32 - -FIXME: remove yodl refs. - -[FIXME: THIS DOCUMENTED IS OUTDATED] - -No, there's no reason to be concered, Lily should work in -Windows-NT(/95/98?) too. The setup may not be easy or smooth. This -document will help you getting started. - - -@section DISCLAIMER - -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 @strong{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. - -``Ok, thanks for the suggestions. I can't run Linux or I don't want -to run Unix. What can I expect?'' - -@itemize @bullet -@item LilyPond development is moving quite fast, and all developers use Unix. - Newly added features may require some attention to get them to work. -@item LilyPond depends on a number of other packages that usually are - available on Unix boxes, but are not installed by default on Windows. -@end itemize - - -LilyPond will now install/extract in a unix-like tree: -@example - - usr/[local/]bin/ - usr/[local/]share/lilypond/* - -@end example - -etc. - -Lily runs in a the unix-like Cygnus gnu-windows environment; -hopefully Cygnus will adopt the @file{/usr/[local/]} tree too. - -@* -If you really don't want usr/ in your root directory, but rather scatter -your programs and packages all over your harddisk, do something like: -@example - - md lilypond - cd lilypond - unzip ../lilypond-0.1.77.exe.zip - -@end example - -and add @file{lilypond/usr/bin} to your @file{PATH} and -@file{lilypond/usr/share/lilypond} to your @file{LILYINCLUDE}. - - -If you've received a binary release of LilyPond (@file{.exe.zip}), -you may skip the following sections. - - -It can be done! Occasionally, the Cygnus b19.1 cross compiler and -utilities under GNU/Linux are used to make the binary @file{.exe.zip} -releases (some makefile hacking was needed to build this stuff). Jeffrey -Reed tries to keep-up with LilyPond development, and is doing quite -well. His latest release is available on -@uref{http://home.austin.rr.com/jbr/jeff/lilypond/}. - - -I have heard of such tools that think they're probably much smarter than the -packager and thus decide for themselves that they don't need to unpack certain -files (e.g., empty directories such as bin/out). - -To unpack the lilypond sources, you should do something like: @example - - tar zxf releases/lilypond-x.y.z.tar.gz - -@end example - - -If you're familiar with the GNU/Cygnus development package, you may skip -this. - -Don't forget to set -@example - - /start/settings/control-panel/system/environment/system-variables: - GCC_EXEC_PREFIX=/Cygnus/b19/H-i386-cygwin32/lib/gcc-lib/ - MAKE_MODE=UNIX - -@end example - -You want to run bash, while building Lily: -@example - - c:\bash - bash-2.01$ - -@end example - -The install instructions mention something like: -@example - - configure - make - make install - -@end example - -Now for a small UNIX lesson: The current working directory (cwd) is -by default not in your PATH, like it is under DOS (for security reasons). -Check this by looking at the output of: -@example - - echo $PATH - -@end example - -The cwd looks like @code{'::'} or @code{':.'}. If it's not there, you may -add the cwd to your path: -@example - - PATH=$PATH:. - -@end example - -or you must use './' when issuing a command in th cwd, try: -@example - - ./configure - make - -@end example - -My point of reference comes from 15 odd years working with a variety -of @code{UNIX} platforms. I am relatively new to Windows-NT and, even -though I am a card carrying @code{UNIX} bigot, I am excited about the -NT OS. My goals for lilypond are to give back to the Free Software -Foundation a little of what they have given me over the years and to -contribute to the lilypond project by supporting a Windows-NT port. I -hope that someday we can distribute and run lilypond on the NT OS in a -much more native fashion. - -@itemize @bullet - -@item Building lilypond on Windows-NT -@item Maintaining lilypond on Windows-NT -@item Running lilypond on Windows-NT - -@end itemize - - -Currently as stated above lilypond is primarily a @code{UNIX} thing. -The Windows-NT port is based on the @code{UNIX} environment provided by -@uref{http://www.cygnus.com,Cygnus}. Therefore the first step is to -download and install the Cygnus development kit: - -@uref{http://www.cygnus.com/misc/gnu-win32/} - -Please follow the documentation Cygnus has on there web site for -downloading and installing. The important part is that you down load -the entire development kit. I believe it is @file{full.exe}. The -installation will ask you where you want to install it. I will refer -to Cygnus installation directory as @file{/gnuwin32/cygwin-b20}. There -should be a @file{README} file that contains installation instructions. -After the installation is complete you should have a @emph{Cygnus} -shortcut in your @emph{Program} section of your @emph{Start Menu}. This -shortcut is your door to the @code{UNIX} world and I will refer to the -resulting window as a @file{bash} shell. - -The shortcut points to @file{/gnuwin32/cygwin-b20/cygnus.bat}. The -following is my @file{cygnus.bat} file. - -@example - -@@ECHO OFF -rem default environment - -rem GNU cygnus installation - -SET CYGREL=B19.1 -SET MAKE_MODE=unix -SET LOCAL_ROOT=d:\gnuwin32 -SET LOCAL_FS=d:/gnuwin32 -SET LOCAL_DIR=d:/gnuwin32/cygwin-b20 -SET CYGROOT=%LOCAL_ROOT%\cygwin-b20 -SET CYGFS=%LOCAL_FS%/cygwin-b20 -SET TCL_LIBRARY=%CYGROOT%\share\tcl8.0 -rem -rem This was not in the original but is needed by lots of packages -rem -SET BISON_SIMPLE=%CYGFS%/share/bison.simple - -rem -rem I place the cygnus stuff in front of /WINNT -rem - -SET PATH=d:\bin;%LOCAL_ROOT%\bin;%CYGROOT%\H-i586-cygwin32\bin;%PATH% -SET MANPATH=%LOCAL_ROOT%\man;%LOCAL_ROOT%\cygwin-b20\full-man\man -SET INFOPATH=%LOCAL_FS%/cygwin-b20/full-man/info;%LOCAL_FS%/cygwin-b20/info;%LOCAL_DIR%/info - -rem General tools not included with Cygnus Development Kit - -rem CVS - -SET PATH=%PATH%;%LOCAL_ROOT%\cvs-1.9.28\bin -SET INFOPATH=%INFOPATH%;%LOCAL_FS%/cvs-1.9.28/info -SET MANPATH=%MANPATH%;%LOCAL_ROOT%\cvs-1.9.28\man - -rem EMACS - -SET PATH=%PATH%;%LOCAL_ROOT%\emacs-19.34\bin -SET INFOPATH=%INFOPATH%;%LOCAL_FS%/emacs-19.34/info - -rem VIM - -SET VIM=%LOCAL_ROOT%\vim-4.6\doc -SET PATH=%PATH%;%LOCAL_ROOT%\vim-4.6 - -rem TeX - -SET PATH=%PATH%;%LOCAL_ROOT%\texmf\miktex\bin - -rem a2ps - -SET PATH=%PATH%;%LOCAL_ROOT%\a2ps-4.10\bin -SET INFOPATH=%INFOPATH%;%LOCAL_FS%/a2ps-4.10/info -SET MANPATH=%MANPATH%;%LOCAL_ROOT%\a2ps-4.10\man - -rem python - -SET PATH=%PATH%;\Program Files\Python - -rem perl - -SET PATH=%PATH%;\qub - -rem yodl - -uname -sv -bash -login - -@end example - -Please look over this carefully. Be careful with the forward and -backward slash notations. The paths specified were done for good -reasons. Maybe someday we will all be using @code{UNC}. Note the -@code{BISON} entry and the @code{PATH} ordering in particular. Also note -that the generic @file{cygnus.bat} you will be looking at does not -include alot of the packages listed. We will be installing some of -these. - -The installation also suggests that you create a directory @file{/bin} -and copy @file{/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/sh.exe} to -@file{/bin}. The @file{sh.exe} shell provided by Cygnus is a descendant -of the @file{ash} shell. The @file{sh.exe} shell has improved greatly -and is much faster than the @file{bash} shell for script invocations. -So this is my recommendation for post installation steps. From a -@file{bash} shell: - -@itemize @bullet -@item @code{cd /} -@item @code{mkdir bin} -@item @code{cd /bin} -@item @code{cp /gnuwin32/cygwin-b20/H-i586-cygwin32/bin/sh.exe sh.exe} -@item @code{cp /gnuwin32/cygwin-b20/H-i586-cygwin32/bin/bash.exe bash.exe} -@item @code{cd /} -@item @code{mkdir /tmp} -@item @code{chmod a+rwx tmp} -@item @code{mkdir /etc} -@item @code{cd /etc} -@item @code{mkpasswd -l > passwd} -@item @code{mkgroup -l > group} -@end itemize - - -There is also some discussion of how you want to @emph{mount} the Cygnus -development kit. @emph{mount} is a @code{UNIX} term that refers to the -mechanism used to provide a disk resource to the filesystem. Cygnus -supplies a mechinism for @emph{mounting} a filesystem as a @code{DOS} like -resource or a @code{UNIX} like resource. Among other things this -attempts to deal with the text file carriage return line feed on -@code{DOS} versus the line feed on @code{UNIX} and the issue that @code{DOS} -has two file types, text and binary. Where @code{UNIX} deals with a -single streams type. My opinion on this matter currently is to use -binary mounts only. This can be accomplished by: - -@itemize @bullet -@item From a bash shell, umount / -@item mount -b d: / -@end itemize - -If you have other disks that you intend to use for data generated by -cygnus tools you will have to mount those devices with the @emph{-b} -switch. - - -@uref{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/egcs.html} - -Cygnus now distributes the ecgs compiler with cygwin-b20. - - -@uref{http://www.gnu.org/order/ftp.html} - -Considering the origin of the major contributors of lilypond, this is a -must. However before we actually do a @strong{GNU} build we have to -discuss some caveats of the Windows-NT OS in particular the naming of -executable files. @code{Windows-NT} uses a .exe extension where @code{UNIX} -does not use an extension. This causes a problem during the -installation portion of a @strong{GNU} build. The following script can be -used to help alleviate this problem. - -@example - -#!/bin/sh - -realinstall=/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/install.exe -args='' -while [ $# -ne 0 ] -do - case $1 in - -*) args="$args $1" - ;; - - *) if [ -f $1.exe ]; then - args="$args $1.exe" - else - args="$args $1" - fi - ;; - esac - shift -done - -$realinstall $args - -@end example - -I place this in script @file{~/bin}. The LilyPond configure, build, -and install process handles this with it's own install script. In -addition there are patches to the cygnus install command that also -deals with this problem. Having said that, here is how one -might build the @emph{gettext} package. - -@itemize @bullet -@item download the package from one of the ftp sites. -@item From a bash shell, cd ~/usr/src. -@item tar zxf gettext-0.10.tar.gz -@item cd gettext-0.10 -@item ./configure --prefix=$CYGFS/H-i586-cygwin32 -@item make -@item make install -@end itemize - - -@uref{http://www.gnu.org/order/ftp.html} - -Following the instructions for @emph{gettext} package to download, build, -and install the @emph{groff} package. - - -@uref{http://www.python.org} - -Python is the scripting language of choice for a lilypond build. -There is a native @code{Windows-NT} self extracting binary distribution -available. I recommend installing Python in a directory that does -@strong{not} have spaces. And then place it in the bash shell path by -editing $CYGFS/cygnus.bat. - - -@uref{http://www.cpan.org} - -I believe perl is used in some legacy scripts to date. There is a -native @code{Windows-NT} self extracting binary distribution available. -I recommend installing Perl in a directory that does @strong{not} have -spaces. And then place it in the bash shell path by editing -$CYGFS/cygnus.bat. - -The development methodology of @emph{LilyPond} relies on a the following -directory structure: - - -@example - -$HOME/usr/src/ - |-releases/ - |-patches/ - |-test/ - -@end example - -@table @samp - -@item releases/ Downloaded and generated releases live here. For -example @file{lilypond-1.1.17.tar.gz}. - -@item patches/ Downloaded and generated patches live here. For -example @file{lilypond-1.1.17.diff.gz}. - -@item test/ This directory is used to generate releases and patches. - -@end table - -I strongly recommend using this file structure to build @emph{yodl} and -@emph{lilypond}. - -@itemize @bullet -@item download the package from -@uref{http://www.xs4all.nl/~jantien/yodl/} to -@file{$HOME/usr/src/releases}. -@item From a bash shell, cd @file{$HOME/usr/src}. -@item tar zxf releases/yodl-@emph{}.tar.gz -@item cd yodl-@emph{} -@item ./configure --prefix=/gnuwin32/yodl-@emph{} --srcdir=. -Since @emph{yodl} is under development I choose to install it in a -version rooted directory. This allows me to test newly released -versions without losing a known working version. - -@item make -@item make install -@item place it in the bash shell path by editing $CYGFS/cygnus.bat. -For example: -@example -rem yodl - -SET PATH=%PATH%;%LOCAL_ROOT%\yodl-1.31.7\bin - - -@end example - -@end itemize - - - -GUILE, GNU's Ubiquitous Intelligent Language for Extension, is a -library that implements the Scheme language plus various convenient -facilities. It's designed so that you can link it into an application -or utility to make it extensible. GNU's plan is to link this library -into all GNU programs that call for extensibility. - -@itemize @bullet -@item download guile-1.3 patch from -@uref{http://home.austin.rr.com/jbr/jeff/lilypond/guile.patch} and save it -to @file{/tmp/guile.patch}. -@item download guile-1.3 from one of GNU's ftp sites. -@item From a bash shell, tar zxf guile-1.3.tar.gz -@item cd guile-1.3 -@item patch -p2 < /tmp/guile.patch -@item LD=/gnuwin32/cygwin-b20/H-i586-cygwin32/bin/ld \ @* - ./configure --prefix=$CYGFS/H-i586-cygwin32 -@item make sure bin_PROGRAMS macro in libguile/Makefile does @emph{not} have the -.exe extension during the build -@item make -@item make sure bin_PROGRAMS in libguile/Makefile @emph{does} have the -.exe extension during the install. Yuck. -@item make install -@end itemize - - -@itemize @bullet -@item download the package from -@uref{http://www.cs.uu.nl/people/hanwen/lilypond/} to -@file{$HOME/usr/src/releases}. -@item From a bash shell, cd @file{$HOME/usr/src}. -@item tar zxf releases/lilypond-@emph{}.tar.gz -@item cd lilypond-@emph{} -@item ./configure --prefix=/gnuwin32/lilypond-@emph{} \ @* - --srcdir=. @* -Since @emph{lilypond} is under development I choose to install it in a -version rooted directory. This allows me to test newly released -versions without losing a known working version. -@item make -@item make install -@item place it in the bash shell path by editing $CYGFS/cygnus.bat. -For example: -@example -rem lilypond - -SET PATH=%PATH%;%LOCAL_ROOT%\lilypond-1.1.17\bin - - -@end example - -@end itemize - - -If you have built @emph{lilypond} on @code{Windows-NT} using the directory - and the process described -in section FIXME, then you are ready to maintain -@emph{lilypond}. It can not be that easy!? Well, there is one caveat. -Currently to use the @file{stepmake/bin/release.py} and -@file{stepmake/bin/package-diff.py} scripts you need to obtain/build a -version of @emph{python} that was built with @strong{Cygnus} development kit. -The process I used is as follows: - -@itemize @bullet -@item obtain python source from @uref{http://www.python.org} -@item tar zxf /tmp/python-@emph{}.tar.gz -@item cd python-@emph{} -@item configure --prefix=/gnuwin32/Python-@emph{} -@item edit toplevel @file{Makefile} @code{EXE} macro so it reads @code{EXE=.exe} -@item make -@item make install -@item place it in the bash shell path by editing $CYGFS/cygnus.bat. -For example: -@example -rem python - -SET PATH=%PATH%;%LOCAL_ROOT%\python-1.5.1\bin - - -@end example - -@end itemize - -I choose to build @emph{lilypond} with the standard @code{Windows-NT} -@emph{python} and use the @strong{Cygnus} version for using the release -scripts. This way I can make sure the @code{Windows-NT} @emph{python} -version is able to build @emph{lilypond}. Currently there are several -issues with the release scripts. Using @code{os.link} and -@code{os.system(set -x;...)} are to name a few. - -To generate a new release and patch you must use the directory -. And follow the -instructions found in @file{PATCH.txt}. Editing -@file{Documentation/AUTHORS.yo}, @file{VERSION}, and @file{NEWS} is also -required. When my edits are complete and tested I: - -@itemize @bullet -@item Edit @file{config.make} and change @emph{python} path to the -@strong{Cygnus} version: @code{PYTHON=/gnuwin32/Python-1.5.1/bin/python}. -@item make release -@end itemize - -The new release is placed in @file{releases} directory and the patch is -placed in the @file{patches} directory. I email the new patch to -@email{gnu-music-discuss@@gnu.org}. More than one patch a day can be -generated by: - -@itemize @bullet -@item cd $HOME/usr/src -@item tar zxf releases/lilypond-@emph{}.@emph{} -@item use your normal configure -@item make edits -@item Change @file{VERSION} to increment @emph{} -@item Change @file{NEWS} -@item make release -@end itemize - - -We are now distributing a formated binary distribution for -Windows-NT. Please refer to -@uref{http://home.austin.rr.com/jbr/jeff/lilypond/} for current news, -download, installation, and running information. - -Jeffrey B. Reed @email{daboys@@austin.rr.com} - -@section RUNNING LILYPOND -- by Dominique Cretel - -You may want to refer to section FIXME, for more current -information about downloading, installing, and running the Windows-NT -binary distribution. - -@enumerate i -@item First, I have download tha 0.1.64 version of LilyPond music software. - -@item Then I extract it in a temp directory, and I move the directory -"lilypond-0.1.64" to the root directory of my D drive. - -@item I go to the D:\Lilypond-0.1.64\tex directory to modify the -lilyponddefs.tex file (lines 75 and 84), and comment all -cmbx15 ans cmbx14, and replace them by cmbx12. - -@item build a command file like this: -Note: I use MiKTeX to process the tex file generated. - -@example - ----begin ly2dvi.bat -echo off -set ver=0.1.64 -set path=%path%;d:\lilypond-%ver%\bin -lilypond -I d:\lilypond-%ver%\init %1 -rem *** pause - -set path=c:\texmf\miktex\bin;%path% -set TEXINPUTS=%TEXINPUTS%;d:\lilypond-%ver%\tex -set MFINPUTS=%MFINPUTS%;d:\lilypond-%ver%\mf -tex %1.tex -rem *** pause - -dvips %1.dvi -rem *** pause - -set path=%path%;d:\gstools\gsview -gsview32 %1.ps ----end ly2dvi.bat - -@end example - -@item execute lilypond by doing: -@example - -ly2ps silly - -@end example - -@end enumerate - -Note: -@* -You'll better have to put the SET commands lines in a separate command -file to avoid consumming each time environnment ressources. - -Bye,@* -Dominique Cretel @email{dominique.cretel@@cfwb.be} - -@section PROBLEMS AND ANWSWERS - -This is all to confusing. I have: -@enumerate i -@item downloaded @file{/tmp/lilypond-0.1.78.tar.gz} -@item @example - - cd ~/usr/src - -@end example - -@item @example - - tar zxf /tmp/lilypond-0.1.78.tar.gz - -@end example - -@item @example - - ./configure --prefix=/users/jeff/lilypond-0.1.78 \--enable-tex-prefix=/users/jeff/lilypond-0.1.78/texmf \--enable-tex-dir=/users/jeff/lilypond-0.1.78/texmf/tex \--enable-mf-dir=/users/jeff/lilypond-0.1.78/texmf/mf - -@end example - -@item @example - - make - -@end example - -@item @example - - make install - -@end example - -@end enumerate - -I did have a problem with lilypond.info. And I will look into this -further. After mending lilypond.info issue, it compiled and install -with no problems. - -I have 64 Meg of physical memory and 64 Meg of swap. Actually I need -to increase the swap space. If a memory problem is occuring it most -likely is during the link process of lilypond. There is a boat load -of objects to link. - -Jan the mount -b stuff is confussing to me. I have the entire system -mounted _without_ -b and only use -b on certain paths for programs -that create binary files that do not use O_BINARY open option. By the -way the midi file open is one of these cases, I need to look into -that. I have had no problems with this methodology. - - -The windows multiroot filesystem is an utterly broken concept. Please -do everything on one (urg) drive, C:. - -@example - -> configure -> creating cache ./config.cache -> [..] -> creating config.make -> creating config.hh -> cd: lstat /d failed - -@end example - -Ok, this looks like another stupid windows problem. -You're working on 'drive D:', right? - -I can think of some solutions, but i don't know if they work; -i just had to do some work in windows some time ago. If you -have problems with this, please ask @email{gnu-win32@@cygnus.com}. -I'll start with the simplest: -@itemize @bullet - @item do everything on drive C:, or - @item explicitely mount drive d:, work from there: - @example - - mkdir -p /mnt/d - mount d: /mnt/d - cd /mnt/d/lilypond-x.y.z/ - -@end example - - @item make d:/ the root of cygnus, in cmd.exe/command.exe do: - @example - - umount / - mount d: / - -@end example - -@end itemize - - -> - First I have installed Python (for win32) "Pyth151.exe" and "Configure -@* -> don't find it. I had to put it in the path for configure find it? -@* - -Yes, of course. It should be possible to have different versions of tools -installed (e.g. perl 4 and perl 5). The best way to tell people (or tools -like configure) which one to use is to put it in the path? - -Another small unix lesson: Where under dos each program installs itself -into a nice directory -@example - - c:\DosProgram\* - -@end example - -under unix, installation is handled centrally. Executables go in -@file{/usr/bin} (or @file{/usr/local/bin}), and are always in your path. - - -@example - -> 4. make -C lily don't work. I get an error (see below). I get several -> object files in the ./lily/out directory (34 files: 17 *.dep, 16 *.o, -> and 1 *.hh): -> [...] -> include/engraver-group.hh:35: virtual memory exhausted -> make: *** [out/bar-grav.o] Error 1 -> bash-2.01$ - - -@end example - -Ok, so everything works now, there's only some error with one of the -source files. Lets see which one (and now the cc's now why they're -reading this :-) - -It looks like you've run out of memory. You should compile without -optimisation, gcc/egcs need a lot of memory for optimising. -Reconfigure without optimisation: -@example - - configure --disable-optimise - -@end example - -or edit @file{config.make}: -@example - - ## USER_CXXFLAGS = -g # -O no optimise! - USER_CXXFLAGS = -g - -@end example - -There are some other things to look at: how much RAM do you have -(please say something > 8Mb :-)? Although it might be an egcs bug, -you should have a look at the size of your swap file. -For an US version of windows, you should find it here: -@example - - /start/settings/control-panel/system/performance/virtual-memory - -@end example - -you see, amongst others, these entries: -@example - - paging file size for selected drive: - - space-available: xx - initial-size: xx - maximum-size: xx - - total paging file size for all drives - - currently allocated: xx - -@end example - -Try to set: -@example - - initial-size: 64 - maximum-size: 128 - -@end example - -Make sure that: -@itemize @bullet -@item maximum-size >= 128 Mb -@item urrently-allocated + space-available >= 128 Mb -@end itemize - - -@bye diff --git a/Documentation/programmer/hacking.texi b/Documentation/programmer/hacking.texi deleted file mode 100644 index da36f2f0ef..0000000000 --- a/Documentation/programmer/hacking.texi +++ /dev/null @@ -1,856 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename internals.info -@settitle LilyPond internals - -@node Top, LilyPond internals, (dir), (dir) -@top - - -@menu -* LilyPond internals:: -* Overview:: -* mudela:: -* Request_engraver:: -* Graphic elements:: -* Score elements:: -* Items:: -* Spanners:: -* Future work:: -* Coding standards:: -* Making patches:: - -@end menu - -@node LilyPond internals, , Top, Top -@menu -* Overview:: Overview -* mudela:: mudela -* Request_engraver:: Request_engraver -@end menu - - -@chapter Getting involved - -Please help us make LilyPond a better program. You can help LilyPond in -several ways. Not all tasks requiring programming or understanding the -full source code. You can write to the mailing list -(@email{gnu-music-discuss@@gnu.org} for more information) - -@unnumberedsubsec Users - -Mutopia needs your help. The mutopia project is a collection of public -domain sheet music. You can help the project by entering music and -submitting. Point your browser to the -@uref{http://sca.uwaterloo.ca/Mutopia, Mutopia webpage} - -@unnumberedsubsec Font designers - -Our set of glyphs (the Feta font) is far from complete. If you know a -little MetaFont you can contribute a glyph - -@unnumberedsubsec Writers - -The documentation of LilyPond and related utilities needs a lot of work. - -@unnumberedsubsec Translators - -LilyPond is completely ready for internationalized messages, but there -are only three translations so far. - -@unnumberedsubsec Hackers - -There are lots of possibilities of improving the program itself. There are -both small projects and big ones. Most of them are listed in the TODO -file. A interesting and very big project is writing a GUI frontend to -LilyPond. - - -@unnumberedsubsec Website designers - -The current website for LilyPond is neat and simple, but it is not very -pretty. We would like to have a website with pretty pictures, one that -looks appealing to new users. - - -@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, Top, Top -@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, Top -@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, , mudela, Top -@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 Graphic elements, , , Top -@section Graphic elements - - -Music notation is composed of a sets of interrelated glyphs. In -Lilypond every glyph usually is represented by one object, a so-called -Graphic Object. The primary relations between graphic objects involve -positions: - -@itemize -@item consecutive notes are printed left to right, grouped in a staff -@item simultaneous notes are horizontally aligned (internally grouped in -a paper column). -@item the staccato mark is horizontally centered on the note it applies -to. -@end itemize - -The abstract encoding of such relations is done with the concept -@dfn{reference point}. The reference point (in X direction) of the -staccato mark is the note it applies to. The (X) position of the -staccato mark is stored relative to the position of the note head. This -means that the staccato will always maintain a fixed offset wrt to the -note head, whereever the head is moved to. - -In the same vein, all notes on a staff have their Y positions stored -relative to an abstract object called Axis_group_spanner. If the -Axis_group_spanner of one staff is moved, the absolute Y positions of -all objects in that spanner change along, in effect causing the staff -and all its contents to move as a whole. - -Each graphic object stores a pointer and an relative offset for each -direction: one for the X-axis, one for the Y-axis. For example, the X -parent of a Note_head usually is a Note_column. The X parent of a -Note_column usually is either a Collision or a Paper_column. The X -parent of a Collision usually is a Paper_column. If the Collision -moves, all Note_heads that have that Collision as parent also move, but -the absolute position of the Paper_column does not change. - -To build a graphical score with Graphic_elements, conceptually, one -needs to have one Root object (in Lilypond: Line_of_score), and -recursively attach objects to the Root. However, due to the nature -of the context selection mechanisms, it turns out to be more -advantageous to construct the tree the other way around: first small -trees (note heads, barlines etc.) are created, and these are -subsequently composed into larger trees, which are finally hung on a -Paper_column (in X direction) or Line_of_score (in Y direction). - -The structure of the X,Y parent relations are determined by the -engravers and notation contexts: - -The most important X-axis parent relation depends on the timing: notes -that come earlier are attached to Paper_column that will be positioned -more to the left. - -The most important Y-axis relation depends on containment of contexts: -notes (created in a Thread or Voice context) are put in the staff where -the originating context lives in. - -Graphical_axis_groups are special graphic objects, that are designed to -function as a parent. The size of a Graphical_axis_groups group is the -union of its children. - -@node Score elements, , , Top - -Besides relative positions there are lots of other relations between -elements. Lilypond does not contain other specialized relation -management (Like the relative positioning code). In stead, objects can -be connected through dependencies, which sets the order in which objects -are to be processed. - -Example: the direction of a beamed stem should equal the direction of -the beam. When the stem is a added to the beam, a dependency on the -beam is set in the stem: this means that @code{Beam::do_pre_processing -()} (which does various direction related things) will be called before -@code{Stem::do_pre_processing ()}. - -The code that manages dependencies resides in the class -@code{Score_element}, a derived class of @code{Graphical_element}. The -bulk of the code handles line breaking related issues. - -To sketch the problems with line breaking: suppose a slur spans a line -break, -@example - -c4( c'''' c | \break d d )d - -@end example -In this case, the slur will appear as two parts, the first part spanning -the first three notes (the @code{c}s), the second spanning the last -three (the @code{d}s). Within Lilypond this is modeled as breaking the -slur in parts: from the Original slur, two new clones of the old slur -are made. Initially both clones depend on the six notes. After the -hairy code in Score_element, Spanner and Item which does substitutions -in sets of dependencies, the first clone depends on the first three -notes, the second on the last three. - -The major derived classes of Score_element are Item and Spanner. -An item has one horizontal position. A spanner hangs on two items. - -@node Items, , , Top -@section Items - - - -An item is a score element that is associated with only one -Paper_column. Examples are note heads, clefs, sup and superscripts, etc. -Item is a derived class of Score_element. - -The shape of an item is known before the break calculations, and line -spacing depends on the size of items: very wide items need more space -than very small ones. - -An additional complication is the behavior of items at linebreaks. For -example, when you do a time signature change, you get only one symbol. -If it occurs at a linebreak, the new time signature must be printed both -before and after the linebreak. Other `breakable symbols' such as -clefs, and bar lines also exhibit this behavior. - -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. To support this, -breakable items are generated in the three versions: original -(unbroken), left (before line break) and right (after line break). -During the line spacing, these versions are used to try how the spacing -of a line works out. - -Once the definitive spacing is determined, dependencies (and various -other pointers) are substituted such that all dependencies point at the -active items: either they point at the original, or they point at left -and right. - -@node Spanners, , , Top -@section Spanners - -Spanners are symbols that are of variable shape, eg. Slurs, beams, etc. -Spanners is a derived class of Score_element. - -The final shape can only be determined after the line breaking process. -All spanners are spanned on two items, called the left and right -boundary item. The X reference point is the left boundary item. - - -@node Future work, , , Top -@section Future work - -There are plans to unify Spanner and Item, so there will no longer be -such a clear distinction between the two. Right now, Score_elements are -always either Item or either Spanner. - -Most of the properties of a graphic object are now member variables of -the classes involved. To offer configurability, we want to move these -variables to scheme (GUILE) variables, and no longer use C++ code to -calculate them, but use Scheme functions. - -@node Coding standards, , , Top - -@chapter CodingStyle - standards while programming for GNU -LilyPond - -Functions and methods do not return errorcodes. - - -@unnumberedsubsec Languages - -C++ and Python are preferred. Perl is not. Python code should use an -indent of 8, using TAB characters. - -@unnumberedsubsec Filenames - -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 - -Standard GNU coding style is used. 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. - -The hungarian notation is to be used when variables are not declared -near usage (mostly in member variables and functions). - -@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. - -@node Making patches, , , Top - - -@unnumberedsec name - - -PATCHES - track and distribute your code changes - -This page documents how to distribute your changes to GNU lilypond - -We would like to have unified context diffs with full pathnames. A -script automating supplied with Lily. - -Distributing a change normally goes like this: - -@itemize @bullet -@item make your fix/add your code -@item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi -@item generate a patch, -@item e-mail your patch to one of the mailing lists - gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org -@end itemize - -Please do not send entire files, even if the patch is bigger than the -original. A patch makes it clear what is changed, and it won't -overwrite previous (not yet released) changes. - -@unnumberedsec Generating a patch - -Simple version: run - -@example - make -C lilypond-x.y.z/ distclean - make -C lilypond-x.y.z.NEW/ distclean - diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/ -@end example - -Complicated (but automated) version: - -In @file{VERSION}, set MY_PATCH_LEVEL: - -@example - - VERSION: - ... - MY_PATCH_LEVEL=jcn1 - -@end example - -In @file{CHANGES}, enter a summary of changes: - -@example - pl 0.1.73.jcn1 - - added PATCHES.texi -@end example - -Then, from the top of Lily's source tree, type - -@example - make release -@end example - -These handy python scripts assume a directory structure which looks -like: - -@example - - lilypond -> lilypond-x.y.z # symlink to development directory - lilypond-x.y.z/ # current development - patches/ # patches between different releases - releases/ # .tar.gz releases - -@end example - -(Some scripts also assume this lives in @file{$HOME/usr/src}). - - -@unnumberedsec Applying patches - - -If you're following LilyPond development regularly, you probably want to -download just the patch for each subsequent release. -After downloading the patch (into the patches directory, of course), simply -apply it: - -@example - - gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E - -@end example - -and don't forget to make automatically generated files: - -@example - - autoconf footnote(patches don't include automatically generated files, - i.e. file(configure) and files generated by file(configure).) - - configure - -@end example - - -@bye - - diff --git a/Documentation/programmer/regression-test.tely b/Documentation/programmer/regression-test.tely deleted file mode 100644 index 082a1205ad..0000000000 --- a/Documentation/programmer/regression-test.tely +++ /dev/null @@ -1,348 +0,0 @@ -\input texinfo @c -*-texinfo-*- vim:tw=72 -@setfilename regression-test.info -@settitle LilyPond Regression test - -@c fool ls-latex -@ignore -@author Han-Wen Nienhuys and Jan Nieuwenhuizen -@title LilyPond Regression test -@end ignore - -@node Top, , , - -@section Introduction - -This document tries give an brief overview of LilyPond features. When -the text correspond with the shown notation, we consider LilyPond -Officially BugFree (tm). This document is intended for finding bugs, -and documenting bugfixes. - -@section Notes and rests - -Rests. Note that the dot of 8th, 16th and 32nd rests rest should be -next to the top of the rest. All rests except the whole rest are -centered on the middle staff line. - -@mudelafile{rest.ly} - -Note head shapes are settable. The stem endings should be adjusted -per note head. If you want different note head styles on one stem, -you must create a special context called Thread. - -Harmonic notes have a different shape and different -dimensions. Nevertheless, noteheads in both styles can be combined, on -either up or down stems. - -@mudelafile{noteheadstyle.ly} - -Noteheads can have dots, and rests can too. Augmentation dots should -never be printed on a staff line, but rather be shifted vertically. They -should go up, but in case of multiple parts, the down stems have down -shifted dots. (Wanske p. 186) In case of chords, all dots should be in -a column. The dots go along as rests are shifted to avoid collisions. - -@mudelafile{dots.fly} - -Multiple measure rests do not collide with barlines and clefs. They -are not expanded when you set @code{Score.skipBars}. Although the -multi-measure-rest is a Spanner, minimum distances are set to keep it -colliding from barlines. - -@mudelafile{multi-measure-rest.ly} - -If @code{Score.skipBars} is set, -the signs for four, two, and one measure rest are combined to -produce the graphical representation of rests for up to 10 bars. -The number of bars will be written above the sign. - -@mudelafile{mm-rests2.ly} - -A sharp sign after a double sharp sign, as well as a flat sign -after a double flat sign is automatically prepended with a -natural sign. - -@mudelafile{double-single-acc.ly} - -@section Stems - -Stem tremolos or rolls are tremolo signs that look like beam segments -crossing stems. If the stem is in a beam, the tremolo must be parallel -to the beam. If the stem is invisible (eg. on a whole note), the -tremolo must be centered on the note. - -@mudelafile{stem-tremolo.ly} - -Chord tremolos look like beams, but are a kind of repeat symbol. -To avoid confusion, chord tremolo beams do not reach the stems, but -leave a gap. Chord tremolo beams on half notes are not ambiguous, -as half notes cannot appear in a regular beam, and should reach the -stems. - -@mudelafile{chord-tremolo.sly} - -Beams, stems and noteheads often have communication troubles, since -the two systems for y dimensions (1 unit = staffspace, 1 unit = 1 -point) are mixed. - -Stems, beams, ties and slurs should behave similarly, when placed -on the middle staff line. Of course stem-direction is down for high -notes, and up for low notes. - -@mudelafile{stem-direction.sly} - -Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}. - -@mudelafile{stem-direction-down.ly} - -@section Scripts - -The staccato dot (and all scripts with follow-into-staff set), must -not be on staff lines. - -@mudelafile{staccato-pos.sly} - -@section Grace notes - -Grace notes are typeset as an encapsulated piece of music. You can -have beams, notes, chords, stems etc. within a @code{\grace} section. -Slurs that start within a grace section, but aren't ended are attached -to the next normal note. Grace notes have zero duration. If there -are tuplets, the grace notes won't be under the brace. Grace notes -can have accidentals, but they are (currently) spaced at a fixed -distance. Grace notes (of course) come before the accidentals of the -main note. Grace notes can also be positioned after the main note. - -Grace notes without beams should have a slash, if @code{flagStyle} is -not set. Main note scripts don't end up on the grace note. - -@mudelafile{grace.ly} - - -@section Beams, slurs and other spanners - -Beaming is generated automatically. Beams may cross bar lines. In that -case, line breaks are forbidden. Yet clef and key signatures are -hidden just as with breakable bar lines. - -@mudelafile{beaming.ly} - -Beams should behave reasonably well, even under extreme circumstances. -Stems may be short, but noteheads should never touch the beam. - -@mudelafile{beam-extreme.ly} - -Beams should always reach the middle staff line. The second beam -counting from the note head side, should never be lower than the -second staff line. This does not hold for grace note beams. -Override with @code{noStemExtend}. - -@mudelafile{beam-position.sly} - -Slurs should look nice and symmetric. The curvature may increase -only to avoid noteheads, and as little as possible. - -@mudelafile{slur-symmetry.ly} -@mudelafile{slur-symmetry-1.ly} - -Ties are strictly horizontal. They are placed in between note heads. -The horizontal middle should not overlap with a staffline. - -@mudelafile{tie.ly} - -When tieing chords, the outer slurs point outwards, the inner slurs -point away from the center of the staff. Override with -@code{tieVerticalDirection}. - -@mudelafile{tie-chord.ly} - -When tieing notes with accidentals across a bar boundary, the accidental -must not be drawn on the note in the new bar. Instead, the next note of -the same pitch in this bar should always show the accidental (even if -it's natural). Slurring a accidentaled note to a natural one across bar -boundaries should be explicit. - -Pitches can be verified by printing them with the @code{NoteNames} context. - -@mudelafile{tie-accidental.ly} - -Beams can be typeset over fixed distance aligned staffs, beam -beautification doesn't really work, but knees do. Beams should be -behave well, wherever the switching point is. - -@mudelafile{beam-cross-staff.ly} - -The same goes for slurs. They behave decently when broken across -linebreak. - -@mudelafile{slur-cross-staff.ly} - -Tuplets are indicated by a bracket with a number. There should be no -bracket if there is one beam that matches the length of the tuplet. -The bracket does not interfere with the stafflines, and the number is -centered in the gap in the bracket. - -@mudelafile{tup.ly} - -@section Repeats - -LilyPond has three modes for repeats: folded, unfolded and -semi-unfolded. Unfolded repeats are fully written out. Semi unfolded -repeats have the body written and all alternatives sequentially. -Folded repeats have the body written and all alternatives -simultaneously. If the number of alternatives is larger than the -repeat count, the excess alternatives are ignored. If the number of -alternatives is smaller, the first alternative is multiplied to get to -the number of repeats. - -Unfolded behavior: - -@mudelafile{repeat-unfold.ly} - -Volta (Semi folded) behavior. Voltas can start on non-barline moments. -If they don't barlines should still be shown. - -@mudelafile{repeat-volta.ly} - -Folded. This doesn't make sense without alternatives, but it works. - -@mudelafile{repeat-fold.ly} - -@section Lyrics - -Lyrics can be set to a melody automatically. Excess lyrics will be -dumped. Lyrics will not be set over rests. You can have melismata -either by setting a property melismaBusy, or by setting -automaticMelismas (which will set melismas during slurs and ties). If -you want a different order than first Music, then Lyrics, you must -precook a chord of staffs/lyrics and label those. Of course -@code{\rhythm} ignores any other rhythms in the piece. Hyphens and -extenders do not assume anything about lyric lengths, so they continue -to work. - -@mudelafile{lyric-combine.ly} - -@section Multiple notes - -Rests should not collide with beams, stems and noteheads. Rests may -be under beams. Rests should be move by integral number of spaces -inside the staff, and by half spaces outside. Notice that the half -and whole rests just outside the staff get ledger lines in different -cases. - -@mudelafile{rest-collision.ly} - -Normal collisions. We have support for polyphony, where the -middle voices are horizontally shifted. - -@mudelafile{collisions.ly} - -The number of stafflines of a staff can be set with the property -numberOfStaffLines. Ledger lines both on note heads and rests are -adjusted. Barlines also are adjusted. - - -@mudelafile{number-staff-lines.fly} - -@section Spacing - -In a limited number of cases, LilyPond corrects for optical spacing -effects. In this example, space for opposite pointed stems is adjusted - -@mudelafile{stem-spacing.sly} - -If there are accidentals in the music, we add space, but the space -between note and accidentals is less than between the notes with the -same value. Clef changes also get extra space, but not as much as -barlines. - - -Even if a line is very tightly spaced, there will still be room -between prefatory matter and the following notes. The space after the -prefatory is very rigid. In contrast, the space before the barline -must stretch like the space within the measure. - -Tight: - -@mudelafile{spacing-tight.ly} - -Natural: - -@mudelafile{spacing-natural.ly} - -Loose: - -@mudelafile{spacing-loose.ly} - -Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that -lyrics don't collide with barlines. - -@mudelafile{lyrics-bar.ly} - -@section Global stuff - -Breaks can be encouraged and discouraged using @code{\break} and -@code{\nobreak}. They are abbrevs for @code{\penalty} commands. - -@mudelafile{break.ly} - - -Markings that are attached to (invisible) barlines are -delicate: the are attached to the rest of the score without the score -knowing it. Consequently, they fall over often. - -@mudelafile{bar-scripts.ly} - -Staff margins are also markings attached to barlines. They should be -left of the staff, and be centered vertically wrt the staff. They may -be on normal staffs, but also on compound staffs, like the PianoStaff - -@mudelafile{staff-margin.ly} - -Breathing signs, also used for phrasing, do normally not influence -global spacing -- only if space gets tight, notes are shifted to make -room for the breathing sign. Breathing signs break beams running -through their voice. In the following example, the notes in the first -two measures all have the same distance from each other: - -@mudelafile{breathing-sign.ly} - -Fonts are available in a default set of sizes: 11, 13, 16, 20, 23 and -26pt staffheight. Sizes of the text fonts and symbol fonts are made -to match the staff dimensions. - -@mudelafile[nofly]{size11.ly} - -@mudelafile[nofly]{size13.ly} - -@mudelafile[nofly]{size16.ly} - -@mudelafile[nofly]{size20.ly} - -@mudelafile[nofly]{size23.ly} - -@mudelafile[nofly]{size26.ly} - - -@section Clefs and Time Signatures - -The transparent clef should not occupy any space and with style -@code{fullSizeChanges}, the changing clef should be typeset in full -size. For octaviated clefs, the ``8'' should appear closely above or -below the clef respectively. The ``8'' is processed in a convoluted -way, so this is fragile as well. - -@mudelafile{clefs.ly} - -@ignore -@c the input file is too long and does not test for specific bugs -By default, time signatures are written with two numbers. With style -``C'', 4/4 and 2/2 are written with their corresponding symbols and -with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and -9/8 are typeset with symbols, all other signatures retain the default -layout. The style ``1'', gives single number signatures for all -signatures. -% -\mu delafile{time.fly} -@end ignore - -@bye diff --git a/Documentation/regression-test.tely b/Documentation/regression-test.tely new file mode 100644 index 0000000000..082a1205ad --- /dev/null +++ b/Documentation/regression-test.tely @@ -0,0 +1,348 @@ +\input texinfo @c -*-texinfo-*- vim:tw=72 +@setfilename regression-test.info +@settitle LilyPond Regression test + +@c fool ls-latex +@ignore +@author Han-Wen Nienhuys and Jan Nieuwenhuizen +@title LilyPond Regression test +@end ignore + +@node Top, , , + +@section Introduction + +This document tries give an brief overview of LilyPond features. When +the text correspond with the shown notation, we consider LilyPond +Officially BugFree (tm). This document is intended for finding bugs, +and documenting bugfixes. + +@section Notes and rests + +Rests. Note that the dot of 8th, 16th and 32nd rests rest should be +next to the top of the rest. All rests except the whole rest are +centered on the middle staff line. + +@mudelafile{rest.ly} + +Note head shapes are settable. The stem endings should be adjusted +per note head. If you want different note head styles on one stem, +you must create a special context called Thread. + +Harmonic notes have a different shape and different +dimensions. Nevertheless, noteheads in both styles can be combined, on +either up or down stems. + +@mudelafile{noteheadstyle.ly} + +Noteheads can have dots, and rests can too. Augmentation dots should +never be printed on a staff line, but rather be shifted vertically. They +should go up, but in case of multiple parts, the down stems have down +shifted dots. (Wanske p. 186) In case of chords, all dots should be in +a column. The dots go along as rests are shifted to avoid collisions. + +@mudelafile{dots.fly} + +Multiple measure rests do not collide with barlines and clefs. They +are not expanded when you set @code{Score.skipBars}. Although the +multi-measure-rest is a Spanner, minimum distances are set to keep it +colliding from barlines. + +@mudelafile{multi-measure-rest.ly} + +If @code{Score.skipBars} is set, +the signs for four, two, and one measure rest are combined to +produce the graphical representation of rests for up to 10 bars. +The number of bars will be written above the sign. + +@mudelafile{mm-rests2.ly} + +A sharp sign after a double sharp sign, as well as a flat sign +after a double flat sign is automatically prepended with a +natural sign. + +@mudelafile{double-single-acc.ly} + +@section Stems + +Stem tremolos or rolls are tremolo signs that look like beam segments +crossing stems. If the stem is in a beam, the tremolo must be parallel +to the beam. If the stem is invisible (eg. on a whole note), the +tremolo must be centered on the note. + +@mudelafile{stem-tremolo.ly} + +Chord tremolos look like beams, but are a kind of repeat symbol. +To avoid confusion, chord tremolo beams do not reach the stems, but +leave a gap. Chord tremolo beams on half notes are not ambiguous, +as half notes cannot appear in a regular beam, and should reach the +stems. + +@mudelafile{chord-tremolo.sly} + +Beams, stems and noteheads often have communication troubles, since +the two systems for y dimensions (1 unit = staffspace, 1 unit = 1 +point) are mixed. + +Stems, beams, ties and slurs should behave similarly, when placed +on the middle staff line. Of course stem-direction is down for high +notes, and up for low notes. + +@mudelafile{stem-direction.sly} + +Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}. + +@mudelafile{stem-direction-down.ly} + +@section Scripts + +The staccato dot (and all scripts with follow-into-staff set), must +not be on staff lines. + +@mudelafile{staccato-pos.sly} + +@section Grace notes + +Grace notes are typeset as an encapsulated piece of music. You can +have beams, notes, chords, stems etc. within a @code{\grace} section. +Slurs that start within a grace section, but aren't ended are attached +to the next normal note. Grace notes have zero duration. If there +are tuplets, the grace notes won't be under the brace. Grace notes +can have accidentals, but they are (currently) spaced at a fixed +distance. Grace notes (of course) come before the accidentals of the +main note. Grace notes can also be positioned after the main note. + +Grace notes without beams should have a slash, if @code{flagStyle} is +not set. Main note scripts don't end up on the grace note. + +@mudelafile{grace.ly} + + +@section Beams, slurs and other spanners + +Beaming is generated automatically. Beams may cross bar lines. In that +case, line breaks are forbidden. Yet clef and key signatures are +hidden just as with breakable bar lines. + +@mudelafile{beaming.ly} + +Beams should behave reasonably well, even under extreme circumstances. +Stems may be short, but noteheads should never touch the beam. + +@mudelafile{beam-extreme.ly} + +Beams should always reach the middle staff line. The second beam +counting from the note head side, should never be lower than the +second staff line. This does not hold for grace note beams. +Override with @code{noStemExtend}. + +@mudelafile{beam-position.sly} + +Slurs should look nice and symmetric. The curvature may increase +only to avoid noteheads, and as little as possible. + +@mudelafile{slur-symmetry.ly} +@mudelafile{slur-symmetry-1.ly} + +Ties are strictly horizontal. They are placed in between note heads. +The horizontal middle should not overlap with a staffline. + +@mudelafile{tie.ly} + +When tieing chords, the outer slurs point outwards, the inner slurs +point away from the center of the staff. Override with +@code{tieVerticalDirection}. + +@mudelafile{tie-chord.ly} + +When tieing notes with accidentals across a bar boundary, the accidental +must not be drawn on the note in the new bar. Instead, the next note of +the same pitch in this bar should always show the accidental (even if +it's natural). Slurring a accidentaled note to a natural one across bar +boundaries should be explicit. + +Pitches can be verified by printing them with the @code{NoteNames} context. + +@mudelafile{tie-accidental.ly} + +Beams can be typeset over fixed distance aligned staffs, beam +beautification doesn't really work, but knees do. Beams should be +behave well, wherever the switching point is. + +@mudelafile{beam-cross-staff.ly} + +The same goes for slurs. They behave decently when broken across +linebreak. + +@mudelafile{slur-cross-staff.ly} + +Tuplets are indicated by a bracket with a number. There should be no +bracket if there is one beam that matches the length of the tuplet. +The bracket does not interfere with the stafflines, and the number is +centered in the gap in the bracket. + +@mudelafile{tup.ly} + +@section Repeats + +LilyPond has three modes for repeats: folded, unfolded and +semi-unfolded. Unfolded repeats are fully written out. Semi unfolded +repeats have the body written and all alternatives sequentially. +Folded repeats have the body written and all alternatives +simultaneously. If the number of alternatives is larger than the +repeat count, the excess alternatives are ignored. If the number of +alternatives is smaller, the first alternative is multiplied to get to +the number of repeats. + +Unfolded behavior: + +@mudelafile{repeat-unfold.ly} + +Volta (Semi folded) behavior. Voltas can start on non-barline moments. +If they don't barlines should still be shown. + +@mudelafile{repeat-volta.ly} + +Folded. This doesn't make sense without alternatives, but it works. + +@mudelafile{repeat-fold.ly} + +@section Lyrics + +Lyrics can be set to a melody automatically. Excess lyrics will be +dumped. Lyrics will not be set over rests. You can have melismata +either by setting a property melismaBusy, or by setting +automaticMelismas (which will set melismas during slurs and ties). If +you want a different order than first Music, then Lyrics, you must +precook a chord of staffs/lyrics and label those. Of course +@code{\rhythm} ignores any other rhythms in the piece. Hyphens and +extenders do not assume anything about lyric lengths, so they continue +to work. + +@mudelafile{lyric-combine.ly} + +@section Multiple notes + +Rests should not collide with beams, stems and noteheads. Rests may +be under beams. Rests should be move by integral number of spaces +inside the staff, and by half spaces outside. Notice that the half +and whole rests just outside the staff get ledger lines in different +cases. + +@mudelafile{rest-collision.ly} + +Normal collisions. We have support for polyphony, where the +middle voices are horizontally shifted. + +@mudelafile{collisions.ly} + +The number of stafflines of a staff can be set with the property +numberOfStaffLines. Ledger lines both on note heads and rests are +adjusted. Barlines also are adjusted. + + +@mudelafile{number-staff-lines.fly} + +@section Spacing + +In a limited number of cases, LilyPond corrects for optical spacing +effects. In this example, space for opposite pointed stems is adjusted + +@mudelafile{stem-spacing.sly} + +If there are accidentals in the music, we add space, but the space +between note and accidentals is less than between the notes with the +same value. Clef changes also get extra space, but not as much as +barlines. + + +Even if a line is very tightly spaced, there will still be room +between prefatory matter and the following notes. The space after the +prefatory is very rigid. In contrast, the space before the barline +must stretch like the space within the measure. + +Tight: + +@mudelafile{spacing-tight.ly} + +Natural: + +@mudelafile{spacing-natural.ly} + +Loose: + +@mudelafile{spacing-loose.ly} + +Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that +lyrics don't collide with barlines. + +@mudelafile{lyrics-bar.ly} + +@section Global stuff + +Breaks can be encouraged and discouraged using @code{\break} and +@code{\nobreak}. They are abbrevs for @code{\penalty} commands. + +@mudelafile{break.ly} + + +Markings that are attached to (invisible) barlines are +delicate: the are attached to the rest of the score without the score +knowing it. Consequently, they fall over often. + +@mudelafile{bar-scripts.ly} + +Staff margins are also markings attached to barlines. They should be +left of the staff, and be centered vertically wrt the staff. They may +be on normal staffs, but also on compound staffs, like the PianoStaff + +@mudelafile{staff-margin.ly} + +Breathing signs, also used for phrasing, do normally not influence +global spacing -- only if space gets tight, notes are shifted to make +room for the breathing sign. Breathing signs break beams running +through their voice. In the following example, the notes in the first +two measures all have the same distance from each other: + +@mudelafile{breathing-sign.ly} + +Fonts are available in a default set of sizes: 11, 13, 16, 20, 23 and +26pt staffheight. Sizes of the text fonts and symbol fonts are made +to match the staff dimensions. + +@mudelafile[nofly]{size11.ly} + +@mudelafile[nofly]{size13.ly} + +@mudelafile[nofly]{size16.ly} + +@mudelafile[nofly]{size20.ly} + +@mudelafile[nofly]{size23.ly} + +@mudelafile[nofly]{size26.ly} + + +@section Clefs and Time Signatures + +The transparent clef should not occupy any space and with style +@code{fullSizeChanges}, the changing clef should be typeset in full +size. For octaviated clefs, the ``8'' should appear closely above or +below the clef respectively. The ``8'' is processed in a convoluted +way, so this is fragile as well. + +@mudelafile{clefs.ly} + +@ignore +@c the input file is too long and does not test for specific bugs +By default, time signatures are written with two numbers. With style +``C'', 4/4 and 2/2 are written with their corresponding symbols and +with style ``old'', 2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and +9/8 are typeset with symbols, all other signatures retain the default +layout. The style ``1'', gives single number signatures for all +signatures. +% +\mu delafile{time.fly} +@end ignore + +@bye diff --git a/Documentation/topdocs/index.tely b/Documentation/topdocs/index.tely index 88d28769e6..9677961953 100644 --- a/Documentation/topdocs/index.tely +++ b/Documentation/topdocs/index.tely @@ -18,9 +18,6 @@ | Mailing lists | - - Regression test - | News ] @end html @@ -207,9 +204,6 @@ then please mail us! | Mailing lists | - - Regression test - | News ] @end html diff --git a/Documentation/user/ly2dvi.texi b/Documentation/user/ly2dvi.texi new file mode 100644 index 0000000000..d7cf664d12 --- /dev/null +++ b/Documentation/user/ly2dvi.texi @@ -0,0 +1,260 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ly2dvi.info +@settitle ly2dvi + +@chapter Ly2dvi + +@section DESCRIPTION +ly2dvi is a Python 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. + +The majority of this utility came from a bourne script written by Jan +Arne Fagertun name @file{ly2dvi}. + +@section SYNOPSIS + + ly2dvi [options] inputfile[.ly] [....] + + +@section OPTIONS + +@table @samp +@item -D,--debug + Set debug mode. There are two levels - in level one some debug + info is written, in level two the command @strong{set -x} is run, which + echoes every command in the ly2dvi script. +@item -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@}} +@item -H,--Heigth= + Set paper heigth (points). Used together with width and LaTeX name of + papersize in case of papersize unknown to ly2dvi. +@item -K,--keeplilypond + Keep LilyPond output after the run. +@item -L,--landscape + Set landscape orientation - portrait is the default. + (@strong{-L} produces @code{\usepackage[landscape]@{article@}}) +@item -N,--nonumber + Switch off page numbering. +@item -O,--orientation= + Set orientation landscape - obsolete, use @strong{-L} instead. +@item -P,--postscript + In addition to the DVI file, also Generate a postsript file. +@item -W,--Width= + Set paper width (points). Used together with heigth and LaTeX name of + papersize in case of papersize unknown to ly2dvi. +@item -d,--dependencies + Tell lilypond to make dependencies file. +@item -h,--help + Print help. +@item -k,--keeply2dvi + Keep the LaTeX file after the run. +@item -l,--language= + Specify LaTeX language. + (@strong{-l norsk} produces @code{\usepackage[norsk]@{babel@}}). +@item -o,--output= + Set output directory. +@item -p,--papersize= + Specify papersize. + (@strong{-p a4} produces @code{\usepackage[a4paper]@{article@}}) +@item -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. +@end table + + +@section Features + +ly2dvi responds to several parameters specified in the mudela +file. They are overridden by corresponding command line options. + +@table @samp +@item language=""; + Specify LaTeX language +@item latexheaders=""; + Specify additional LaTeX headers file +@item orientation=""; + Set orientation. +@item paperlinewidth=""; + Specify the width (pt, mm or cm) of the printed lines. +@item papersize=""; + Specify name of papersize. +@end table + +@section Environment + +@table @samp +@item LILYPONDPREFIX + Sets the root directory of the LilyPond installation +@item LILYINCLUDE + Additional directories for input files. +@item TMP + Temporary directory name. Default is /tmp +@end table + +@section 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: + +@table @samp +@item title + The title of the music. Centered on top of the first page. +@item subtitle + Subtitle, centered below the title. +@item poet + Name of the poet, leftflushed below the below subtitle. +@item composer + Name of the composer, rightflushed below the subtitle. +@item metre + Meter string, leftflushed below the below poet. +@item opus + Name of the opus, rightflushed below the below composer. +@item arranger + Name of the arranger, rightflushed below the opus. +@item instrument + Name of the instrument, centered below the arranger +@item piece + Name of the piece, leftflushed below the instrument +@end table + +@file{$LILYPONDPREFIX/share/.lilyrc $HOME/.lilyrc ./.lilyrc} are files +to set up default running conditions. On Windows OS initialization +files are named @file{_lilyrc}. The file syntax is as follows: + +@example +VARIABLE-NAME=VALUE +@end example + + +Where @strong{VARIABLE-NAME} is the name of the variable documented below +and @strong{VALUE} is either a string, a 1, or a 0. All files are parsed, +in the shown sequence. In the current version the following are +allowed: + +@table @samp +@item DEBUG=value +This turns off (default) or on the debug capabilities. Possible +values are 0 (off) and 1 (on). +@item DEPENDENCIES=value +This turns off (default) or on the ability to generate a Makefile +dependency list. Possible values are 0 (off) and 1 (on). +@item KEEPLILYPOND=value +This turns off (default) or on the ability to keep the log file +associated with the LilyPond job. Possible values are 0 (off) and 1 +(on). +@item KEEPLY2DVI=value +This turns off (default) or on the ability to keep the temporary files +that are generated by the ly2dvi job. Possible values are 0 (off) and +1 (on) +@item LANGUAGE=value +Specify LaTeX language. Possible value is a valid LaTeX language. +@item LATEXHF=value +Specify additional LaTeX headers file. Possible value is a file +specification. +@item LILYINCLUDE=value +Additional directories for input files. Possible value is a delimited +directory path list. +@item LILYPONDPREFIX=value +This defines the LilyPond root directory. Possible value is a valid +directory specification to the LilyPond distribution location. +@item NONUMBER=value +This turns off (default) or on the page numbering capability. +Possible values are 0 (page numbering enabled) and 1 (page numbering +disabled). +@item ORIENTATION=value +This sets the image orientation. Possible values are +portrait (default) and landscape. +@item OUTPUTDIR=value +This defines the directory where the resultant files will be +generated. Possible value is a valid directory specification. +Default is the current working directory. +@item PAPERSIZE=value +This defines the papersize the image will be sized to fit. Possible +values are a0, a1, a2, a3, a4 (default), a5, a6, a7, a8, a9, a10, b0, +b1, b2, b3, b4, b5, archA, archB, archC, archD, archE, flsa, flse, +halfletter, ledger, legal, letter, or note. +@item PHEIGHT=value +Specify paperheight (points - an inch is 72.27, a cm is 28.453 points). +@item POSTSCRIPT=value +This turns off (default) or on the capability of additionally +generating a postscript file. Possible values are 0 (off) and 1 (on). +@item PWIDTH=value +Specify paperwidth (points - an inch is 72.27, a cm is 28.453 points). +@item SEPARATE=value +This turns off (default) or on the capability of generating multiple +dvi and postscript files from multiple source files. The default is +to generate a concatenation of the source files. Possible values are +0 (single file) and 1 (separate files). +@item TMP=value +This defines the emporary directory. Actually this is not used at the +present. Possible value is a valid directory specification that is +writable to the user. +@end table + +@section Initialization Sequence +The initialization process reads inputs for several sources. Below is +a list of priorities for lowest to hightest proirity. + +@itemize @bullet +@item Program's defaults +@item Values found in LilyPond output file +@item Environment variables +@item $LILYPONDPREFIX/share/lilypond/.lilyrc +@item $HOME/.lilyrc +@item ./.lilyrc +@item command line options +@end itemize + +Note that this differs slightly from the original bourne shell +version. + +@section See Also + +lilypond(1), tex(1), latex(1) + +@section Bugs + +If you have found a bug, you should send a bugreport. + +@itemize @bullet +@item Send a copy of the input which causes the error. +@item Send a description of the platform you use. +@item Send a description of the LilyPond and ly2dvi version you use. +@item Send a description of the bug itself. +@item Send it to @email{bug-gnu-music@@gnu.org} (you don't have to subscribe + to this mailinglist). +@end itemize + +@section 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 + +@section Authors +Python Version author: +@email{daboys@@austin.rr.com, Jeffrey B. Reed}, +@uref{http://home.austin.rr.com/jbr/jeff/lilypond/} + +Original bourne shell version author: +@email{Jan.A.Fagertun@@energy.sintef.no, Jan Arne Fagertun}, +@uref{http://www.termo.unit.no/mtf/people/janaf/} + + + + diff --git a/Documentation/user/midi2ly.texi b/Documentation/user/midi2ly.texi new file mode 100644 index 0000000000..7a4609d436 --- /dev/null +++ b/Documentation/user/midi2ly.texi @@ -0,0 +1,46 @@ +\input texinfo @c -*-texinfo-*- +@setfilename midi2ly.info +@settitle midi2ly + + +@chapter midi2ly + +@section DESCRIPTION +midi2ly translates a MIDI input file to Mudela (GNU LilyPond source +format). midi2ly is part of the GNU LilyPond music typesetting package. + + midi2ly [options] midi-file + +@section OPTIONS + +@table @samp +@item -b, --no-quantify, + Write exact durations, e.g.: `a4*385/384'. +@item -D, --debug, + Print lots of debugging stuff. +@item -h, --help, + Show a summary of usage. +@item -I, --include=@file{DIR}, + Add DIR to search path. +@item -k, --key=ACC[:MINOR], + Set default key. ACC > 0 sets number of sharps; ACC < 0 sets number + of flats. A minor key is indicated by ":1". +@item -n, --no-silly, + Assume no plets or double dots, assume smallest (reciprocal) duration 16. +@item -o, --output=@file{FILE}, + Set @file{FILE} as default output. +@item -p, --no-plets, + Assume no plets. +@item -q, --quiet, + Be quiet. +@item -s, --smallest=N, + Assume no shorter (reciprocal) durations than N. +@item -v, --verbose, + Be verbose. +@item -w, --warranty, + Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!) +@item -x, --no-double-dots, + Assume no double dotted notes. +@end table + +@bye diff --git a/VERSION b/VERSION index 8bbc082e15..85c8fef60c 100644 --- a/VERSION +++ b/VERSION @@ -1,8 +1,8 @@ PACKAGE_NAME=LilyPond MAJOR_VERSION=1 MINOR_VERSION=3 -PATCH_LEVEL=34 -MY_PATCH_LEVEL=jcn3 +PATCH_LEVEL=35 +MY_PATCH_LEVEL= # use the above to send patches: MY_PATCH_LEVEL is always empty for a # released version. diff --git a/input/test/GNUmakefile b/input/test/GNUmakefile index 85f2a1fbca..8fea0aed67 100644 --- a/input/test/GNUmakefile +++ b/input/test/GNUmakefile @@ -1,7 +1,7 @@ # input/test/Makefile depth = ../.. -examples= # font20 +examples= font20 LOCALSTEPMAKE_TEMPLATES=mutopia include $(depth)/make/stepmake.make diff --git a/lily/lookup.cc b/lily/lookup.cc index 72d188b18e..818ce69e3f 100644 --- a/lily/lookup.cc +++ b/lily/lookup.cc @@ -285,6 +285,8 @@ Lookup::text (String style, String text, Paper_def *paper_l) lines[i] = str; } + if (!lines.size()) + return Molecule(); SCM first = gh_list (ly_symbol2scm ("text"), ly_str02scm (lines[0].ch_C()), diff --git a/make/out/lilypond.lsm b/make/out/lilypond.lsm index 8aa23b5e34..f0df4de561 100644 --- a/make/out/lilypond.lsm +++ b/make/out/lilypond.lsm @@ -1,15 +1,15 @@ Begin3 Title: LilyPond -Version: 1.3.34 -Entered-date: 15MAR00 +Version: 1.3.35 +Entered-date: 16MAR00 Description: Keywords: music notation typesetting midi fonts engraving Author: hanwen@cs.uu.nl (Han-Wen Nienhuys) janneke@gnu.org (Jan Nieuwenhuizen) Maintained-by: hanwen@stack.nl (Han-Wen Nienhuys) Primary-site: sunsite.unc.edu /pub/Linux/apps/sound/convert - 1000k lilypond-1.3.34.tar.gz + 1000k lilypond-1.3.35.tar.gz Original-site: ftp.cs.uu.nl /pub/GNU/LilyPond/development/ - 1000k lilypond-1.3.34.tar.gz + 1000k lilypond-1.3.35.tar.gz Copying-policy: GPL End diff --git a/make/out/lilypond.spec b/make/out/lilypond.spec index 6556e08990..f3e0fbcedd 100644 --- a/make/out/lilypond.spec +++ b/make/out/lilypond.spec @@ -1,9 +1,9 @@ Name: lilypond -Version: 1.3.34 +Version: 1.3.35 Release: 1 Copyright: GPL Group: Applications/Publishing -Source0: ftp.cs.uu.nl:/pub/GNU/LilyPond/development/lilypond-1.3.34.tar.gz +Source0: ftp.cs.uu.nl:/pub/GNU/LilyPond/development/lilypond-1.3.35.tar.gz Summary: A program for printing sheet music. URL: http://www.cs.uu.nl/~hanwen/lilypond # get Packager from (undocumented?) ~/.rpmmacros!