+@example
+input/regression/out-www/collated-files.tely
+@end example
+
+
+Note the --verbose flag - this is from the make variable
+LILYPOND_BOOK_VERBOSE which is added to the make variable
+LILYPOND_BOOK_FLAGS.
+
+Now found the invocation to write some of the image files. It's
+like this:
+
+@example
+/home/phil/lilypond-git/build/out/bin/lilypond
+ -I /home/phil/lilypond-git/input/regression/
+ -I ./out-www -I /home/phil/lilypond-git/input
+ -I /home/phil/lilypond-git/Documentation
+ -I /home/phil/lilypond-git/Documentation/snippets
+ -I /home/phil/lilypond-git/input/regression/
+ -I /home/phil/lilypond-git/Documentation/included/
+ -I /home/phil/lilypond-git/build/mf/out/
+ -I /home/phil/lilypond-git/build/mf/out/
+ -I /home/phil/lilypond-git/Documentation/pictures
+ -I /home/phil/lilypond-git/build/Documentation/pictures/./out-www
+ -dbackend=eps
+ --formats=ps,png,pdf
+ -dinclude-eps-fonts
+ -dgs-load-fonts
+ --header=doctitle
+ --header=doctitlecs
+ --header=doctitlede
+ --header=doctitlees
+ --header=doctitlefr
+ --header=doctitlehu
+ --header=doctitleit
+ --header=doctitleja
+ --header=doctitlenl
+ --header=doctitlezh
+ --header=texidoc
+ --header=texidoccs
+ --header=texidocde
+ --header=texidoces
+ --header=texidocfr
+ --header=texidochu
+ --header=texidocit
+ --header=texidocja
+ --header=texidocnl
+ --header=texidoczh
+ -dcheck-internal-types
+ -ddump-signatures
+ -danti-alias-factor=2
+ -I "/home/phil/lilypond-git/build/out/lybook-db"
+ -I "/home/phil/lilypond-git/build/input/regression"
+ -I "/home/phil/lilypond-git/input/regression"
+ -I "/home/phil/lilypond-git/build/input/regression/out-www"
+ -I "/home/phil/lilypond-git/input"
+ -I "/home/phil/lilypond-git/Documentation"
+ -I "/home/phil/lilypond-git/Documentation/snippets"
+ -I "/home/phil/lilypond-git/input/regression"
+ -I "/home/phil/lilypond-git/Documentation/included"
+ -I "/home/phil/lilypond-git/build/mf/out"
+ -I "/home/phil/lilypond-git/build/mf/out"
+ -I "/home/phil/lilypond-git/Documentation/pictures"
+ -I "/home/phil/lilypond-git/build/Documentation/pictures/out-www"
+ --formats=eps
+ --verbose
+ -deps-box-padding=3.000000
+ -dread-file-list
+ -dno-strip-output-dir
+ "/home/phil/lilypond-git/build/out/lybook-db/snippet-names--415419468.ly"'
+@end example
+
+Note the --verbose. This causes 100s of lines of Lily debug output.
+But at present I can't work out where the flag comes from. Later.
+
+
+@node Building a bibliography
+@subsection Building a bibliography
+
+Bibliography files contain a list of citations, like this:
+
+@example
+@@Book@{vinci,
+ author = @{Vinci, Albert C.@},
+ title = @{Fundamentals of Traditional Music Notation@},
+ publisher = @{Kent State University Press@},
+ year = @{1989@}
+@}
+@end example
+
+There are a variety of types of citation (e.g. Book (as above),
+article, publication). Each cited publication has a list of
+entries that can be used to identify the publication.
+Bibliograpies are normally stored as files with a .bib
+extension. One part of the doc-build process is transforming the
+bibliography information into @code{texinfo} files. The commands
+to do this are in the @file{GNUmakefile} in the
+@file{Documentation} directory.
+
+A typical line of the makefile to translate a single bibliography
+is:
+
+@example
+$(outdir)/colorado.itexi:
+ BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
+ -s $(top-src-dir)/Documentation/lily-bib \
+ -o $(outdir)/colorado.itexi \
+ $(src-dir)/essay/colorado.bib
+@end example
+
+Line by line:
+
+@example
+$(outdir)/colorado.itexi:
+@end example
+
+We're making the file @file{colorado.itexi} and so this is the
+make instruction.
+
+@example
+ BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
+@end example
+
+It's in the @file{essay} directory and we want to run the
+bib2texi.py script against it.
+
+@example
+ -s $(top-src-dir)/Documentation/lily-bib \
+@end example
+
+The style template is @file{lily-bib.bst} and is found in the
+@file{Documentation} directory.
+
+@example
+ -o $(outdir)/colorado.itexi \
+@end example
+
+The output file in @file{colorado.itexi}.
+
+@example
+ $(src-dir)/essay/colorado.bib
+@end example
+
+The input file is @file{colorado.bib} in the @file{essay}
+directory.
+
+The @code{bib2texi} Python script used to be used with a variety
+of options, but now is always called using the same options, as
+above. Its job is to create the file containing the options for
+@code{bibtex} (the program that actually does the translation),
+run bibtex, and then clean up some temporary files. Its main
+"value add" is the creation of the options file, using this code:
+
+@example
+open (tmpfile + '.aux', 'w').write (r'''
+\relax
+\citation@{*@}
+\bibstyle@{%(style)s@}
+\bibdata@{%(files)s@}''' % vars ())
+@end example
+
+The key items are the style file (now always lily-bib for us) and
+the input file.
+
+The style file is written in its own specialised language,
+described to some extent at
+
+@example
+@uref{http://amath.colorado.edu/documentation/LaTeX/reference/faq/bibtex.pdf}
+@end example
+
+The file @file{lily-bib.bst} also has fairly extensive commenting.
+
+
+@node Website build
+@section Website build
+
+@warning{This information applies only to the standard @code{make
+website} from the normal build directory. The process is
+different for @code{dev/website-build}.}
+
+The rule for make website is found in GNUmakefile.in:
+
+@example
+website:
+$(MAKE) config_make=$(config_make) \
+ top-src-dir=$(top-src-dir) \
+ -f $(top-src-dir)/make/website.make \
+ website
+@end example
+
+This translates as:
+
+@example
+make --no-builtin-rules config_make=./config.make \
+ top-src-dir=/home/phil/lilypond-git \
+ -f /home/phil/lilypond-git/make/website.make \
+ website
+@end example
+
+which has the effect of setting the variables @code{config_make}
+and @code{top-src-dir} and then processing the file
+@code{git/make/website.make} with the target of website.
+
+@code{website.make} starts with the following:
+
+@example
+ifeq ($(WEBSITE_ONLY_BUILD),1)
+@end example
+
+which checks to see whether the variable @code{WEBSITE_ONLY_BUILD}
+was set to one on the command line. This is only done for
+standalone website builds, not in the normal case. The result of
+the test determines the value of some variables that are set. A
+number of other variables are set, in order to establish locations
+of various files. An example is:
+
+@example
+CREATE_VERSION=python $(script-dir)/create-version-itexi.py
+@end example
+
+The rule for website is:
+
+@smallexample
+website: website-texinfo website-css website-pictures website-examples web-post
+ cp $(SERVER_FILES)/favicon.ico $(OUT)/website
+ cp $(SERVER_FILES)/robots.txt $(OUT)/website
+ cp $(top-htaccess) $(OUT)/.htaccess
+ cp $(dir-htaccess) $(OUT)/website/.htaccess
+@end smallexample
+
+so we see that this starts by running the rules for 5 other
+targets, then finishes by copying some files. We'll cover that
+later - first @code{website-texinfo}. That rule is:
+
+@example
+website-texinfo: website-version website-xrefs website-bibs
+ for l in '' $(WEB_LANGS); do \
+ if test -n "$$l"; then \
+ langopt=--lang="$$l"; \
+ langsuf=.$$l; \
+ fi; \
+ $(TEXI2HTML) --prefix=index \
+ --split=section \
+ --I=$(top-src-dir)/Documentation/"$$l" \
+ --I=$(top-src-dir)/Documentation \
+ --I=$(OUT) \
+ $$langopt \
+ --init-file=$(texi2html-init-file) \
+ -D web_version \
+ --output=$(OUT)/"$$l" \
+ $(top-src-dir)/Documentation/"$$l"/web.texi ; \
+ ls $(OUT)/$$l/*.html | xargs grep -L \
+ 'UNTRANSLATED NODE: IGNORE ME' | \
+ sed 's!$(OUT)/'$$l'/!!g' | xargs \
+ $(MASS_LINK) --prepend-suffix="$$langsuf" \
+ hard $(OUT)/$$l/ $(OUT)/website/ ; \
+ done
+@end example
+
+which therefore depends on @code{website-version},
+@code{website-xrefs} and @code{website-bibs}.
+
+@example
+website-version:
+ mkdir -p $(OUT)
+ $(CREATE_VERSION) $(top-src-dir) > $(OUT)/version.itexi
+ $(CREATE_WEBLINKS) $(top-src-dir) > $(OUT)/weblinks.itexi
+@end example
+
+which translates as:
+
+@example
+mkdir -p out-website
+python /home/phil/lilypond-git/scripts/build/create-version-itexi.py
+ /home/phil/lilypond-git > out-website/version.itexi
+python /home/phil/lilypond-git/scripts/build/create-weblinks-itexi.py
+ /home/phil/lilypond-git > out-website/weblinks.itexi
+@end example
+
+So, we make out-website then send the output of
+@code{create-version-itexi.py} to @code{out-website/version.itexi}
+and @code{create-weblinks-itexi.py} to
+@code{out-website/weblinks.itexi}.
+
+@code{create-version-itexi.py} parses the file @code{VERSION} in
+the top source dir. It contains:
+
+@example
+PACKAGE_NAME=LilyPond
+MAJOR_VERSION=2
+MINOR_VERSION=15
+PATCH_LEVEL=13
+MY_PATCH_LEVEL=
+VERSION_STABLE=2.14.2
+VERSION_DEVEL=2.15.12
+@end example
+
+currently. @code{c-v-i.py} parses this to:
+
+@example
+@@c ************************ Version numbers ************
+@@macro version
+2.15.13
+@@end macro
+
+@@macro versionStable
+2.14.2
+@@end macro
+
+@@macro versionDevel
+2.15.12
+@@end macro
+@end example
+
+@code{create-weblinks-itexi.py} creates a load of texi macros (of
+the order of 1000) similar to:
+
+@example
+@@macro manualStableGlossaryPdf
+@@uref@{../doc/v2.14/Documentation/music-glossary.pdf,Music glossary.pdf@}
+@@end macro.
+@end example
+
+It loads its languages from langdefs.py, and therefore outputs the following unhelpful warning:
+
+@code{langdefs.py: warning: lilypond-doc gettext domain not found.}
+
+Next:
+
+@example
+website-xrefs: website-version
+ for l in '' $(WEB_LANGS); do \
+@end example
+
+is the start of the rule, truncated for brevity. This loops
+through the languages to be used on the website, processing some
+variables which I don't fully understand, to run this command:
+
+@smallexample
+python /home/phil/lilypond-git/scripts/build/extract_texi_filenames.py \
+ -I /home/phil/lilypond-git/Documentation \
+ -I /home/phil/lilypond-git/Documentation/"$l" \
+ -I out-website -o out-website --split=node \
+ --known-missing-files= \
+ /home/phil/lilypond-git/scripts/build/website-known-missing-files.txt \
+ -q \
+ /home/phil/lilypond-git/Documentation/"$l"/web.texi ;\
+@end smallexample
+
+There's a good description of what
+@code{extract_texi_filenames.py} does at the top of the script,
+but a shortened version is:
+
+@code{If this script is run on a file texifile.texi, it produces
+a file texifile[.LANG].xref-map with tab-separated entries
+of the form NODE\tFILENAME\tANCHOR.}
+
+An example from
+@code{web.nl.xref-map} is:
+
+@example
+Inleiding Introduction Introduction
+@end example
+
+@code{e-t-f.py} follows the includes from document to document.
+We know some have not been created yet, and
+@code{known-missing-files} option tells @code{e-t-f.py} which
+these are.
+
+It then does this:
+
+@example
+for m in $(MANUALS); do \
+@end example
+
+to run @code{e-t-f.py} against all of the manuals, in each
+language. Next:
+
+@example
+website-bibs: website-version
+ BSTINPUTS=$(top-src-dir)/Documentation/web \
+ $(WEB_BIBS) -s web \
+ -s $(top-src-dir)/Documentation/lily-bib \
+ -o $(OUT)/others-did.itexi \
+ $(quiet-flag) \
+ $(top-src-dir)/Documentation/web/others-did.bib
+@end example
+
+This is half the command. It runs @code{bib2texi.py} on 2
+@code{.bib} files - @code{others-did.bib} and @code{we-wrote.bib}.
+This converts bibliography files into texi files with
+@code{bibtex}.
+
+Next the commands in the @code{website-texinfo} rule are run:
+
+@example
+for l in '' $(WEB_LANGS); do \
+@end example
+
+run @code{texi2html}. This is the program that outputs the
+progress message (found in
+@code{Documentation/lilypond-texi2html.init}):
+
+@code{Processing web site: []}
+
+It also outputs warning messages like:
+
+@code{WARNING: Unable to find node 'Řešení potíží' in book usage.}
+
+@example
+website-css:
+ cp $(top-src-dir)/Documentation/css/*.css $(OUT)/website
+@end example
+
+Copies 3 css files to out-website/website. Then:
+
+@example
+website-pictures:
+ mkdir -p $(OUT)/website/pictures
+ if [ -d $(PICTURES) ]; \
+ then \
+ cp $(PICTURES)/* $(OUT)/website/pictures ; \
+ ln -sf website/pictures $(OUT)/pictures ;\
+ fi
+@end example
+
+which translates as:
+
+@smallexample
+if [ -d Documentation/pictures/out-www ]; \
+ then \
+ cp Documentation/pictures/out-www/* out-website/website/pictures ; \
+ ln -sf website/pictures out-website/pictures ;\
+ fi
+@end smallexample
+
+i.e. it copies the contents of
+@code{build/Documentation/pictures/out-www/*} to
+@code{out-website/website/pictures}. Unfortunately, the pictures
+are only created once @code{make doc} has been run, so an initial
+run of @code{make website} copies nothing, and the pictures on the
+website (e.g. the logo) do not exist. Next:
+
+@example
+website-examples:
+ mkdir -p $(OUT)/website/ly-examples
+ if [ -d $(EXAMPLES) ]; \
+ then \
+ cp $(EXAMPLES)/* $(OUT)/website/ly-examples ; \
+ fi
+@end example
+
+translates to:
+
+@smallexample
+mkdir -p out-website/website/ly-examples
+if [ -d Documentation/web/ly-examples/out-www ]; \
+ then \
+ cp Documentation/web/ly-examples/out-www/* out-website/website/ly-examples ; \
+ fi
+@end smallexample
+
+This does the same with the LilyPond examples (found at
+@uref{http://lilypond.org/examples.html}). Again, these are
+actually only created by @code{make doc} (and since they are
+generated from LilyPond source files, require a working LilyPond
+@code{exe} made with @code{make}). So this does nothing
+initially. Then:
+
+@example
+web-post:
+ $(WEB_POST) $(OUT)/website
+@end example
+
+which is:
+
+@smallexample
+python /home/phil/lilypond-git/scripts/build/website_post.py out-website/website
+@end smallexample
+
+which describes itself as:
+
+@code{This is web_post.py. This script deals with translations
+in the "make website" target.}
+
+It also does a number of other things, including adding the Google
+tracker code and the language selection footer. We're now at
+the end of our story. The final 4 lines of the recipe for website
+are:
+
+@example
+cp $(SERVER_FILES)/favicon.ico $(OUT)/website
+cp $(SERVER_FILES)/robots.txt $(OUT)/website
+cp $(top-htaccess) $(OUT)/.htaccess
+cp $(dir-htaccess) $(OUT)/website/.htaccess
+@end example
+
+The first translates as:
+
+@smallexample
+cp /home/phil/lilypond-git/Documentation/web/server/favicon.ico out-website/website
+@end smallexample
+
+so we see these are just copying the support files for the web
+server.
+
+@subsubheading website.make summary
+
+Recipes in @file{website.make}:
+
+@itemize
+
+@item
+@code{website:}
+this is the "master" rule. It calls the other rules in order,
+then copies some extra files around - see below for further
+of the process it produces.
+
+@item
+@code{website-version}:
+this calls the python scripts below:
+@itemize
+@item
+@example
+scripts/build/create-version-itexi.py
+@end example
+
+This writes a @@version, @@versionStable, and @@versionDevel based
+on the top-level VERSIONS file, to
+@code{out-website/version.itexi}
+
+@item
+@example
+scripts/build/create-weblinks-itexi.py
+@end example
+
+This creates a ton of macros in @code{out-website/weblinks.itexi}.
+Stuff like @@downloadStableLinuxNormal, @@downloadStableWidows,
+@code{@@stableDocsNotationPdf@{@}}, @@downloadDevelSourch-zh.
+
+It's quite monstrous because it deals with combinations of
+stable/devel, source/docs, lang/lang/lang*10, etc.
+
+@end itemize
+
+@item
+@code{website-xrefs:}
+creates files used for complicated "out-of-build" references to
+@code{out-website/*.xref-map}
+
+If you just write @@ref@{@}, then all's groovy and we wouldn't
+need this. But if you write @@rlearning@{@}, then our custom
+texi2html init file needs to know about our custom xref file
+format, which tells our custom texi2html init file how to create
+the link.
+
+GP: we should have a separate @@node to discuss xrefs. Also, take a
+quick look at a generated xref file -- it's basically just a list
+of @@node's [sic teenager pluralization rule] from the file.
+
+@item
+@code{website-bib:}
+generates the bibliography texinfo files from the .bib files - in
+the case of the website build these are @file{others-did.bib} and
+@file{we-wrote.bib}.
+
+@item
+@code{website-texinfo:}
+this is the main part; it calles texi2html to generate the actual
+html. It also has a ton of options to texi2html to pass info to
+our custom init file.
+
+The file actually built is called @file{web.texi}, and is either
+in the @file{Documentation} directory, or a sub-directory specific
+to the language.
+
+The options file is @file{/Documentation/lilypond-texi2html.init}.
+This contains *lots* of option and configuration stuff, and also
+includes the line:
+
+@smallexample
+print STDERR "Initializing settings for web site: [$Texi2HTML::THISDOC@{current_lang@}]\n";
+@end smallexample
+
+This is where one of the console messages is generated.
+
+We have somewhere between 2-4 different ways "to pass info to our
+custom init file". This is highly Not Good (tm), but that's how
+things work at the moment.
+
+After texi2html, it does some black magick to deal with
+untranslated nodes in the translations. Despite writing that
+part, I can't remember how it works. But in theory, you could
+figure it out by copy&pasting each part of the command (by "part",
+I mean "stuff before each | pipe"), substituting the variables,
+then looking at the text that's output. For example,
+
+@example
+ ls $(OUT)/$$l/*.html
+@end example
+
+is going to print a list of all html files, in all languages, in
+the build directory. Then more stuff happens to each of those
+files (that's what xargs does).
+
+@item
+@code{website-css:}
+just copies files to the build dir.
+
+@item
+@code{website-pictures, website-examples:}
+more file copies, with an if statement to handle if you don't have
+any generated pictures/examples.
+
+@item
+@code{web-post:}
+runs:
+
+@example
+scripts/build/website_post.py
+@end example
+
+which, it adds the "this page is translated in klingon" to the
+bottom of html pages, and adds the google analytics javascript.
+It also has hard-coded lilypond version numbers, which is Bad
+(tm).
+
+@end itemize
+
+Here's a summary of what gets called, in what order, when we run
+@code{make website}
+
+@example
+website:
+ website-texinfo:
+ website-version:
+ creates version.itexi and weblinks.itexi
+ website-xrefs:
+ runs extract_texi_filenames.py
+ website-bibs:
+ creates bibliography files, described above
+ website-css:
+ copies css files
+ website-pictures:
+ copies pictures
+ website-examples:
+ copies examples
+ web-post:
+ runs website_post.py
+ Then some file copying
+@end example
+
+@node Building an Ubuntu distro
+@section Building an Ubuntu distro
+
+
+Here's the short instruction on how to create lilybuntu iso image
+(Jonathan Kulp did this on a spare drive,
+but he supposes it can be done in a VM too):
+
+@enumerate
+
+@item
+Install ubuntu, reboot.
+@item
+Run all updates, reboot if asked.
+@item
+Enable src repos, refresh package lists.
+@item
+Install LilyPond build deps:
+@example
+sudo apt-get build-dep lilypond
+@end example
+@item
+Install git and autoconf:
+@example
+sudo apt-get install git-core gitk autoconf
+@end example
+
+@item
+Test to see whether everything works fine now:
+@enumerate
+@item
+use @command{lily-git.tcl} to grab source files
+@item
+go to source dir and do
+@example
+"./autogen.sh" ; make ; make doc
+@end example
+@item
+if all compiles, move on to iso creation...
+@end enumerate
+
+@item
+Download & install "remastersys":
+@uref{http://sourceforge.net/projects/remastersys/, http://sourceforge.net/projects/remastersys/}
+@item
+Copy @command{lily-git.tcl} script file into @file{/etc/skel/}.
+@item
+Modify @file{/etc/remastersys.conf} as desired (change @code{.iso} name,
+default live session username, etc).
+@item
+Remove non-essential desktop software as desired.
+@item
+Create iso:
+@example
+sudo remastersys dist
+@end example
+New iso is in @file{/home/remastersys/remastersys/}.
+@item
+Test iso by installing in VM and repeating steps above for
+getting source files and building lp and docs.
+
+@end enumerate