From 2e5c6b1338ec0dc4a16d154050cd1544ce96ff07 Mon Sep 17 00:00:00 2001 From: Jonathan Kulp Date: Wed, 3 Jun 2009 08:34:52 -0500 Subject: [PATCH] DOCS: additions to LM and CG --- Documentation/devel/compiling.itexi | 66 +++++- Documentation/devel/doc-work.itexi | 80 ++++---- Documentation/devel/lsr-work.itexi | 2 +- Documentation/user/working.itely | 398 +++++++++++++++++++++++++++++++++-- 4 files changed, 478 insertions(+), 68 deletions(-) diff --git a/Documentation/devel/compiling.itexi b/Documentation/devel/compiling.itexi index 0d86cd6..1547353 100644 --- a/Documentation/devel/compiling.itexi +++ b/Documentation/devel/compiling.itexi @@ -1,19 +1,67 @@ @c -*- coding: us-ascii; mode: texinfo; -*- + address@hidden +* Compiling from source:: standard compilation instructions +* Concurrent Stable and Development Versions:: address@hidden menu + @node Compiling LilyPond @chapter Compiling LilyPond address@hidden compile.itely -TODO: ADD -- how to make a stable version and development version coexist on - your system address@hidden Concurrent Stable and Development Versions address@hidden Concurrent Stable and Development Versions -- how to build with debug info +It can be useful to have both the stable and the development versions +of Lilypond available at once. One way to do this on GNU/Linux is to +install the stable version using the precompiled binary, and run the +development version from the source tree. After running @command{make +all} from the top directory of the Lilypond source files, there will +be a binary called @code{lilypond} in the @code{out} directory: -- other compilation tricks for developers address@hidden +<@var{path to}>/lilypond/out/bin/lilypond address@hidden example address@hidden -* Compiling from source:: standard compilation instructions address@hidden menu +This binary can be run without actually doing the @code{make +install} command. The advantage to this is that you can have all +of the latest changes available after pulling from git and running address@hidden all}, without having to uninstall the old version and +reinstall the new. address@hidden compile.itely +So, to use the stable version, install it as usual and use the +normal commands: + address@hidden +lilypond foobar.ly address@hidden example + +To use the development version, create a link to the binary in the +source tree by saving the following line in a file somewhere in your +PATH: + address@hidden +exec <@var{path to}>/lilypond/out/bin/lilypond "$@@" address@hidden example + +Save it as @code{Lilypond} (with a capital L to distinguish it +from the stable @code{lilypond}), and make it executable: + address@hidden +chmod +x Lilypond address@hidden example + +Then you can invoke the development version this way: + address@hidden +Lilypond foobar.ly address@hidden example + + +TODO: ADD + +- how to build with debug info + +- other compilation tricks for developers diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi index b6bbe63..0cbc72f 100644 --- a/Documentation/devel/doc-work.itexi +++ b/Documentation/devel/doc-work.itexi @@ -3,12 +3,12 @@ @chapter Documentation work @menu -* Introduction to documentation work:: -* Texinfo introduction and usage policy:: -* Documentation policy:: -* Tips for writing docs:: -* Updating docs with convert-ly:: -* Translating the documentation:: +* Introduction to documentation work:: +* Texinfo introduction and usage policy:: +* Documentation policy:: +* Tips for writing docs:: +* Updating docs with convert-ly:: +* Translating the documentation:: @end menu @@ -56,13 +56,13 @@ limited documentation help. @section Texinfo introduction and usage policy @menu -* Texinfo introduction:: -* Documentation files:: -* Sectioning commands:: -* LilyPond formatting:: -* Text formatting:: -* Syntax survey:: -* Other text concerns:: +* Texinfo introduction:: +* Documentation files:: +* Sectioning commands:: +* LilyPond formatting:: +* Text formatting:: +* Syntax survey:: +* Other text concerns:: @end menu @@ -458,7 +458,7 @@ B ... @@end itemize - for bulleted lists. @item @@bs - Generates a backslash inside @@warning. - Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@address@hidden@}' + Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@address@hidden@}' (texinfo would also allow \\, but this breaks with PDF output). @item @@ -531,11 +531,11 @@ that all such characters appear in all output formats. @section Documentation policy @menu -* Books:: -* Section organization:: -* Checking cross-references:: -* General writing:: -* Technical writing style:: +* Books:: +* Section organization:: +* Checking cross-references:: +* General writing:: +* Technical writing style:: @end menu @node Books @@ -938,11 +938,11 @@ This also updates translated documentation. @section Translating the documentation @menu -* Getting started with documentation translation:: -* Documentation translation details:: -* Documentation translation maintenance:: -* Translations management policies:: -* Technical background:: +* Getting started with documentation translation:: +* Documentation translation details:: +* Documentation translation maintenance:: +* Translations management policies:: +* Technical background:: @end menu @node Getting started with documentation translation @@ -952,9 +952,9 @@ First, get the sources from the Git repository, see @ref{Documentation translations source code}. @menu -* Translation requirements:: -* Which documentation can be translated:: -* Starting translation in a new language:: +* Translation requirements:: +* Which documentation can be translated:: +* Starting translation in a new language:: @end menu @node Translation requirements @@ -1051,10 +1051,10 @@ Please follow all the instructions with care to ensure quality work. All files should be encoded in UTF-8. @menu -* Files to be translated:: -* Translating the Learning Manual and other Texinfo documentation:: -* Translating the Notation Reference and Application Usage:: -* Translating the Documentation index index.html.in:: +* Files to be translated:: +* Translating the Learning Manual and other Texinfo documentation:: +* Translating the Notation Reference and Application Usage:: +* Translating the Documentation index index.html.in:: @end menu @node Files to be translated @@ -1192,8 +1192,8 @@ easier. These helper scripts make use of the power of Git, the version control system used for LilyPond development. @menu -* Check state of translation:: -* Updating documentation translation:: +* Check state of translation:: +* Updating documentation translation:: @end menu @node Check state of translation @@ -1334,8 +1334,8 @@ be managed, they aim at helping translators, developers and coordinators work efficiently. @menu -* Maintaining without updating translations:: -* Managing documentation translation with Git:: +* Maintaining without updating translations:: +* Managing documentation translation with Git:: @end menu @node Maintaining without updating translations @@ -1443,7 +1443,7 @@ make address@hidden fix-xrefs @noindent This step requires a sucessful documentation build (with @command{make -web}). Some cross-references are broken because they point to a node +doc}). Some cross-references are broken because they point to a node that exists in the documentation in English, which has not been added to the translation; in this case, do not fix the cross-reference but keep it "broken", so that the resulting HTML link will point to an @@ -1499,13 +1499,13 @@ its documentation, and in this case they should be pushed to @code{stable/X.Y} are preferably made on @code{lilypond/X.Ytranslation}. address@hidden @code{lilypond/translation} Git branch may be merged into master only if -LilyPond (@command{make all}) and documentation (@command{make web}) compile -succesfully. address@hidden @code{lilypond/translation} Git branch may be merged into +master only if LilyPond (@command{make all}) and documentation +(@command{make doc}) compile succesfully. @item @code{master} Git branch may be merged into @code{lilypond/translation} whenever @command{make} and @command{make -web} are succesful (in order to ease documentation compilation by +doc} are succesful (in order to ease documentation compilation by translators), or when significant changes had been made in documentation in English in master branch. diff --git a/Documentation/devel/lsr-work.itexi b/Documentation/devel/lsr-work.itexi index 8f38ec2..9ef6661 100644 --- a/Documentation/devel/lsr-work.itexi +++ b/Documentation/devel/lsr-work.itexi @@ -56,7 +56,7 @@ Snippets created or updated in @file{input/new} should be copied to scripts/auxiliar/makelsr.py @end example -Be sure that @command{make web} runs successfully before submitting a +Be sure that @command{make doc} runs successfully before submitting a patch, to prevent breaking compilation. @subheading Formatting snippets in @file{input/new} diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely index 8c5a382..8f1c837 100644 --- a/Documentation/user/working.itely +++ b/Documentation/user/working.itely @@ -22,6 +22,7 @@ this chapter. * Suggestions for writing LilyPond input files:: * When things don't work:: * Scores and parts:: +* Make and Makefiles:: @end menu @@ -170,7 +171,7 @@ lilypond input files becomes vital. @itemize address@hidden @strong{Use an variable for each voice}, with a minimum of address@hidden @strong{Use a variable for each voice}, with a minimum of structure inside the definition. The structure of the @code{\score} section is the most likely thing to change; the @code{violin} definition is extremely unlikely to change @@ -191,7 +192,7 @@ g4 c'8. e16 @end example @item @strong{Separate tweaks from music definitions}. This -point was made in previously, but for large +point was made previously, but for large projects it is absolutely vital. We might need to change the definition of @code{fthenp}, but then we only need to do this once, and we can still avoid touching anything @@ -356,7 +357,7 @@ those definitions in our input files, and I personally find all the @code{#()} somewhat ugly. Let's hide them in another file: @example -%%% save this to a file called "definitions.ly" +%%% save this to a file called "definitions.ily" mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0) #:line(#:dynamic "mp" #:text #:italic "dolce" ))) @@ -367,13 +368,17 @@ inst = #(define-music-function (parser location string) (string?) 'text (markup #:bold (#:box string)))) @end example +We will refer to this file using the @code{\include} command near +the top of the music file. (The extension @code{.ily} is used to +distinguish this included file, which is not meant to be compiled +on its own, from the main file.) Now let's modify our music (let's save this file as @file{"music.ly"}). @c We have to do this awkward example/lilypond-non-verbatim @c because we can't do the \include stuff in the manual. @example -\include "definitions.ly" +\include "definitions.ily" \relative c'' @{ \tempo 4=50 @@ -407,11 +412,11 @@ put the metronome marking above the clef, instead of over the first note. And finally, my composition professor hates @q{C} time signatures, so we'd better make that @q{4/4} instead. -Don't change @file{music.ly}, though. Replace our @file{definitions.ly} +Don't change @file{music.ly}, though. Replace our @file{definitions.ily} with this: @example -%%% definitions.ly +%%% definitions.ily mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0) #:line( #:dynamic "mp" #:text #:italic "dolce" ))) @@ -471,13 +476,13 @@ inst = #(define-music-function (parser location string) (string?) That looks nicer! But now suppose that I want to publish this piece. My composition professor doesn't like @q{C} time signatures, but I'm somewhat fond of them. Let's copy the -current @file{definitions.ly} to @file{web-publish.ly} and +current @file{definitions.ily} to @file{web-publish.ily} and modify that. Since this music is aimed at producing a pdf which will be displayed on the screen, we'll also increase the overall size of the output. @example -%%% definitions.ly +%%% definitions.ily mpdolce = #(make-dynamic-script (markup #:hspace 0 #:translate '(5 . 0) #:line( #:dynamic "mp" #:text #:italic "dolce" ))) @@ -533,30 +538,30 @@ inst = #(define-music-function (parser location string) (string?) @end lilypond Now in our music, I simply replace address@hidden "definitions.ly"} with address@hidden "web-publish.ly"}. Of course, we could make this -even more convenient. We could make a @file{definitions.ly} file which address@hidden "definitions.ily"} with address@hidden "web-publish.ily"}. Of course, we could make this +even more convenient. We could make a @file{definitions.ily} file which contains only the definitions of @code{mpdolce} and @code{inst}, a address@hidden file which contains only the @code{\layout} -section listed above, and a @file{university.ly} file which address@hidden file which contains only the @code{\layout} +section listed above, and a @file{university.ily} file which contains only the tweaks to produce the output that my professor prefers. The top of @file{music.ly} would then look like this: @example -\include "definitions.ly" +\include "definitions.ily" %%% Only uncomment one of these two lines! -\include "web-publish.ly" -%\include "university.ly" +\include "web-publish.ily" +%\include "university.ily" @end example This approach can be useful even if you are only producing one set of parts. I use half a dozen different @q{style sheet} files for my projects. I begin every music -file with @code{\include "../global.ly"}, which contains +file with @code{\include "../global.ily"}, which contains @example -%%% global.ly +%%% global.ily \version @w{"@version{}"} #(ly:set-option 'point-and-click #f) \include "../init/init-defs.ly" @@ -825,3 +830,360 @@ leading to @end lilypond + address@hidden Make and Makefiles address@hidden Make and Makefiles + address@hidden makefiles address@hidden make + +Pretty well all the platforms Lilypond can run on support a software +facility called @code{make}. This software reads a special file called a address@hidden that defines what files depend on what others and what +commands you need to give the operating system to produce one file from +another. For example the makefile would spell out how to produce address@hidden and @code{ballad.midi} from @code{ballad.ly} by +running Lilypond. + +There are times when it is a good idea to create a @code{Makefile} +for your project, either for your own convenience or +as a courtesy to others who might have access to your source files. +This is true for very large projects with many included files and +different output options (e.g. full score, parts, conductor's +score, piano reduction, etc.), or for projects that +require difficult commands to build them (such as address@hidden projects). Makefiles vary greatly in +complexity and flexibility, according to the needs and skills of +the authors. The program GNU Make comes installed on GNU/Linux +distributions and on MacOS X, and it is also available for Windows. + +See the @strong{GNU Make Manual} for full details on using address@hidden, as what follows here gives only a glimpse of what it +can do. + +The commands to define rules in a makefile differ +according to platform; for instance the various forms of Linux and +MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on +MacOS X, you need to configure the system to use the command-line +intepreter. Here are some example makefiles, with versions for both +Linux/MacOS and Windows. + +The first example is for an orchestral work in four +movements with a directory structure as follows: + address@hidden +Symphony/ +|-- MIDI/ +|-- Makefile +|-- Notes/ +| |-- cello.ily +| |-- figures.ily +| |-- horn.ily +| |-- oboe.ily +| |-- trioString.ily +| |-- viola.ily +| |-- violinOne.ily +| `-- violinTwo.ily +|-- PDF/ +|-- Parts/ +| |-- symphony-cello.ly +| |-- symphony-horn.ly +| |-- symphony-oboes.ly +| |-- symphony-viola.ly +| |-- symphony-violinOne.ly +| `-- symphony-violinTwo.ly +|-- Scores/ +| |-- symphony.ly +| |-- symphonyI.ly +| |-- symphonyII.ly +| |-- symphonyIII.ly +| `-- symphonyIV.ly +`-- symphonyDefs.ily address@hidden example + +The @code{.ly} files in the @code{Scores} and address@hidden directories get their notes from @code{.ily} +files in the @code{Notes} directory: + address@hidden +%%% top of file "symphony-cello.ly" +\include ../definitions.ily +\include ../Notes/cello.ily address@hidden example + +The makefile will have targets of @code{score} (entire piece in +full score), @code{movements} (individual movements in full score), +and @code{parts} (individual parts for performers). There +is also a target @code{archive} that will create a tarball of +the source files, suitable for sharing via web or email. Here is +the makefile for GNU/Linux or MacOS X. It should be saved with the +name @code{Makefile} in the top directory of the project: + address@hidden a target or pattern rule is defined, the +subsequent lines must begin with tabs, not spaces.} + address@hidden +# the name stem of the output files +piece = symphony +# determine how many processors are present +CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//` +# The command to run lilypond +LILY_CMD = lilypond -ddelete-intermediate-files \ + -dno-point-and-click -djob-count=$(CPU_CORES) + +# The suffixes used in this Makefile. +.SUFFIXES: .ly .ily .pdf .midi + +# Input and output files are searched in the directories listed in +# the VPATH variable. All of them are subdirectories of the current +# directory (given by the GNU make variable `CURDIR'). +VPATH = \ + $(CURDIR)/Scores \ + $(CURDIR)/PDF \ + $(CURDIR)/Parts \ + $(CURDIR)/Notes + +# The pattern rule to create PDF and MIDI files from a LY input file. +# The .pdf output files are put into the `PDF' subdirectory, and the +# .midi files go into the `MIDI' subdirectory. +%.pdf %.midi: %.ly + $(LILY_CMD) $<; \ # this line begins with a tab + if test -f "$*.pdf"; then \ + mv "$*.pdf" PDF/; \ + fi; \ + if test -f "$*.midi"; then \ + mv "$*.midi" MIDI/; \ + fi + +notes = \ + cello.ily \ + horn.ily \ + oboe.ily \ + viola.ily \ + violinOne.ily \ + violinTwo.ily + +# The dependencies of the movements. +$(piece)I.pdf: $(piece)I.ly $(notes) +$(piece)II.pdf: $(piece)II.ly $(notes) +$(piece)III.pdf: $(piece)III.ly $(notes) +$(piece)IV.pdf: $(piece)IV.ly $(notes) + +# The dependencies of the full score. +$(piece).pdf: $(piece).ly $(notes) + +# The dependencies of the parts. +$(piece)-cello.pdf: $(piece)-cello.ly cello.ily +$(piece)-horn.pdf: $(piece)-horn.ly horn.ily +$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily +$(piece)-viola.pdf: $(piece)-viola.ly viola.ily +$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily +$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily + +# Type `make score' to generate the full score of all four +# movements as one file. +.PHONY: score +score: $(piece).pdf + +# Type `make parts' to generate all parts. +# Type `make foo.pdf' to generate the part for instrument `foo'. +# Example: `make symphony-cello.pdf'. +.PHONY: parts +parts: $(piece)-cello.pdf \ + $(piece)-violinOne.pdf \ + $(piece)-violinTwo.pdf \ + $(piece)-viola.pdf \ + $(piece)-oboes.pdf \ + $(piece)-horn.pdf + +# Type `make movements' to generate files for the +# four movements separately. +.PHONY: movements +movements: $(piece)I.pdf \ + $(piece)II.pdf \ + $(piece)III.pdf \ + $(piece)IV.pdf + +all: score parts movements + +archive: + tar -cvvf stamitz.tar \ # this line begins with a tab + --exclude=*pdf --exclude=*~ \ + --exclude=*midi --exclude=*.tar \ + ../Stamitz/* address@hidden example + + +There are special complications on the Windows platform. After +downloading and installing GNU Make for Windows, you must set the +correct path in the system's environment variables so that the +DOS shell can find the Make program. To do this, right-click on +"My Computer," then choose @code{Properties} and address@hidden Click @code{Environment Variables}, and then +in the @code{System Variables} pane, highlight @code{Path}, click address@hidden, and add the path to the GNU Make executable file, which + will look something like this: + address@hidden +C:\Program Files\GnuWin32\bin address@hidden example + +The makefile itself has to be altered to handle different shell +commands and to deal with spaces that are present +in some default system directories. The @code{archive} target +is eliminated since Windows does not have the @code{tar} command, +and Windows also has a different default extension for midi files. + + address@hidden +## WINDOWS VERSION +## +piece = symphony +LILY_CMD = lilypond -ddelete-intermediate-files \ + -dno-point-and-click \ + -djob-count=$(NUMBER_OF_PROCESSORS) + +#get the 8.3 name of CURDIR (workaround for spaces in PATH) +workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \ + do @echo %%~sb) + +.SUFFIXES: .ly .ily .pdf .mid + +VPATH = \ + $(workdir)/Scores \ + $(workdir)/PDF \ + $(workdir)/Parts \ + $(workdir)/Notes + +%.pdf %.mid: %.ly + $(LILY_CMD) $< # this line begins with a tab + if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab + if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab + +notes = \ + cello.ily \ + figures.ily \ + horn.ily \ + oboe.ily \ + trioString.ily \ + viola.ily \ + violinOne.ily \ + violinTwo.ily + +$(piece)I.pdf: $(piece)I.ly $(notes) +$(piece)II.pdf: $(piece)II.ly $(notes) +$(piece)III.pdf: $(piece)III.ly $(notes) +$(piece)IV.pdf: $(piece)IV.ly $(notes) + +$(piece).pdf: $(piece).ly $(notes) + +$(piece)-cello.pdf: $(piece)-cello.ly cello.ily +$(piece)-horn.pdf: $(piece)-horn.ly horn.ily +$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily +$(piece)-viola.pdf: $(piece)-viola.ly viola.ily +$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily +$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily + +.PHONY: score +score: $(piece).pdf + +.PHONY: parts +parts: $(piece)-cello.pdf \ + $(piece)-violinOne.pdf \ + $(piece)-violinTwo.pdf \ + $(piece)-viola.pdf \ + $(piece)-oboes.pdf \ + $(piece)-horn.pdf + +.PHONY: movements +movements: $(piece)I.pdf \ + $(piece)II.pdf \ + $(piece)III.pdf \ + $(piece)IV.pdf + +all: score parts movements address@hidden example + + +The next Makefile is for a @command{lilypond-book} document done in +LaTeX. This project has an index, which requires that the address@hidden command be run twice to update links. Output files are +all stored in the @code{out} directory for .pdf output and in the address@hidden directory for the html output. + address@hidden +SHELL=/bin/sh +FILE=myproject +OUTDIR=out +WEBDIR=htmlout +VIEWER=acroread +BROWSER=firefox +LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex +LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex +PDF=cd $(OUTDIR) && pdflatex $(FILE) +HTML=cd $(WEBDIR) && latex2html $(FILE) +INDEX=cd $(OUTDIR) && makeindex $(FILE) +PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf & + +all: pdf web keep + +pdf: + $(LILYBOOK_PDF) # begin with tab + $(PDF) # begin with tab + $(INDEX) # begin with tab + $(PDF) # begin with tab + $(PREVIEW) # begin with tab + +web: + $(LILYBOOK_HTML) # begin with tab + $(HTML) # begin with tab + cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab + $(BROWSER) $(FILE)/$(FILE).html & # begin with tab + +keep: pdf + cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab + +clean: + rm -rf $(OUTDIR) # begin with tab + +web-clean: + rm -rf $(WEBDIR) # begin with tab + +archive: + tar -cvvf myproject.tar \ # begin this line with tab + --exclude=out/* \ + --exclude=htmlout/* \ + --exclude=myproject/* \ + --exclude=*midi \ + --exclude=*pdf \ + --exclude=*~ \ + ../MyProject/* address@hidden example + +TODO: make this thing work on Windows + +The previous makefile does not work on Windows. An alternative +for Windows users would be to create a simple batch file +containing the build commands. This will not +keep track of dependencies the way a makefile does, but it at +least reduces the build process to a single command. Save the +following code as @command{build.bat} or @command{build.cmd}. +The batch file can be run at the DOS prompt or by simply +double-clicking its icon. + address@hidden +lilypond-book --output=out --pdf myproject.lytex +cd out +pdflatex myproject +makeindex myproject +pdflatex myproject +cd .. +copy out\myproject.pdf MyProject.pdf address@hidden example + + address@hidden +Application Usage: address@hidden for MacOS X}, address@hidden usage}, address@hidden -- 1.6.0.4