From: fred Date: Tue, 26 Mar 2002 23:31:34 +0000 (+0000) Subject: lilypond-1.3.35 X-Git-Tag: release/1.5.59~1388 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=e9f3581928ab2245cdd0acfba137a9895b27136f;p=lilypond.git lilypond-1.3.35 --- 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