]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/contributor/build-notes.itexi
[doc] Handle leading dash in @code.
[lilypond.git] / Documentation / contributor / build-notes.itexi
index e733d665474d81af79578125ca1974ade19a0608..b84bdbef6067dbae72fd48c29e0ba2ab54a88c99 100644 (file)
@@ -164,9 +164,9 @@ comments, and I'd guess most of it isn't needed.
 We return to @file{stepmake.make}, where we hit the make rule all:
 The first line of this is:
 
-@example
+@smallexample
 -include $(addprefix $(depth)/make/,$(addsuffix -inclusions.make, $(LOCALSTEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which, when the variables are substituted, gives:
 
@@ -181,9 +181,9 @@ error message when the included file doesn't exist).
 
 And the first file doesn't exist.  Nor the second.  Next:
 
-@example
+@smallexample
 -include $(addprefix $(stepdir)/,$(addsuffix -inclusions.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expands to the following files:
 
@@ -202,9 +202,9 @@ that'll be something else to discover.)
 
 Next in @file{stepmake.make}:
 
-@example
+@smallexample
 include $(addprefix $(stepdir)/,$(addsuffix -vars.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expands to:
 
@@ -239,10 +239,10 @@ So now we're back to @file{stepmake.make}.
 
 The next lines are
 :
-@example
+@smallexample
 # ugh. need to do this because of PATH :=$(top-src-dir)/..:$(PATH)
 include $(addprefix $(depth)/make/,$(addsuffix -vars.make, $(LOCALSTEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 and the include expands to:
 
@@ -255,12 +255,12 @@ child @code{make} processes to use them.
 
 The final 4 lines of @file{stepmake.make} are:
 
-@example
+@smallexample
 include $(addprefix $(depth)/make/,$(addsuffix -rules.make, $(LOCALSTEPMAKE_TEMPLATES)))
 include $(addprefix $(stepdir)/,$(addsuffix -rules.make, $(STEPMAKE_TEMPLATES)))
 include $(addprefix $(depth)/make/,$(addsuffix -targets.make, $(LOCALSTEPMAKE_TEMPLATES)))
 include $(addprefix $(stepdir)/,$(addsuffix -targets.make, $(STEPMAKE_TEMPLATES)))
-@end example
+@end smallexample
 
 which expand as follows:
 
@@ -336,7 +336,7 @@ A bit more info from 27 March.  I've put some error traces into
 following lines actually cause the make to run (putting an error
 call above them - no make; below them - make):
 
-@example
+@smallexample
 ifeq ($(out),www)
 # All web targets, except info image symlinks and info docs are
 # installed in non-recursing target from TOP-SRC-DIR
@@ -344,14 +344,15 @@ install-WWW:
        -$(INSTALL) -m 755 -d $(DESTDIR)$(webdir)
        rsync -rl --exclude='*.signature' $(outdir)/offline-root $(DESTDIR)$(webdir)
        $(MAKE) -C Documentation omf-local-install
-@end example
+@end smallexample
 
 I don't currently understand the @code{ifeq}, since @code{$(out)}
-is empty at this point, but the line starting @code{-$(INSTALL)}
+is empty at this point, but the line starting @w{@code{-$(INSTALL)}}
 translates to:
 
 @example
--/usr/bin/python /home/phil/lilypond-git/stepmake/bin/install.py -c -m 755 -d /usr/local/share/doc/lilypond/html
+-/usr/bin/python /home/phil/lilypond-git/stepmake/bin/install.py \
+  -c -m 755 -d /usr/local/share/doc/lilypond/html
 @end example
 
 End of work for Sunday 27th.
@@ -373,9 +374,492 @@ begin from the "make" command).
 @section Doc build
 
 @menu
+* The function of make doc::
 * Building a bibliography::
 @end menu
 
+@node The function of make doc
+@subsection The function of make doc
+
+The following is a set of notes on how make doc functions.
+
+Preliminary question to be answered some time: where do all the
+GNUmakefiles come from.  They're in the build directory, but this
+is not part of source.  Must be the configure script.  And it
+looks like this comes from autogen.sh.  Must at some point kill
+the whole git directory, repull and see what is created when.
+
+Anyway, here's how make doc progresses:
+
+This is the build dependency tree from
+@file{stepmake/stepmake/generic-targets.make}:
+
+@example
+doc: doc-stage-1
+  doc-stage-1:
+        $(MAKE) -C $(depth)/scripts/build out=
+        $(MAKE) out=www WWW-1
+          WWW-1: local-WWW-1
+        $(LOOP)
+          $(MAKE) out=www WWW-2
+          WWW-2: local-WWW-2
+            $(LOOP)
+          $(MAKE) out=www WWW-post
+@end example
+
+@example
+MAKE = make --no-builtin-rules
+-C = Change to directory before make
+@end example
+
+doc-stage-1 does lots of opening and looking in files, but no
+processing.
+
+@example
+Variable LOOP =
+
++ make PACKAGE=LILYPOND package=lilypond -C python
+&& make PACKAGE=LILYPOND package=lilypond -C scripts
+&&  make PACKAGE=LILYPOND package=lilypond -C flower
+&&  make PACKAGE=LILYPOND package=lilypond -C lily
+&&  make PACKAGE=LILYPOND package=lilypond -C mf
+&&  make PACKAGE=LILYPOND package=lilypond -C ly
+&&  make PACKAGE=LILYPOND package=lilypond -C tex
+&&  make PACKAGE=LILYPOND package=lilypond -C ps
+&&  make PACKAGE=LILYPOND package=lilypond -C scm
+&&  make PACKAGE=LILYPOND package=lilypond -C po
+&&  make PACKAGE=LILYPOND package=lilypond -C make
+&&  make PACKAGE=LILYPOND package=lilypond -C elisp
+&&  make PACKAGE=LILYPOND package=lilypond -C vim
+&&  make PACKAGE=LILYPOND package=lilypond -C input
+&&  make PACKAGE=LILYPOND package=lilypond -C stepmake
+&&  make PACKAGE=LILYPOND package=lilypond -C Documentation
+&& true
+@end example
+
+From git grep:
+
+stepmake/stepmake/generic-vars.make has this:
+
+@smallexample
+LOOP=+$(foreach i, $(SUBDIRS), $(MAKE) PACKAGE=$(PACKAGE) package=$(package) -C $(i) $@ &&) true
+@end smallexample
+
+$@ is the name of the target - WWW-1 in this case.
+
+In GNUmakefile.in we find:
+
+@example
+SUBDIRS = python scripts \
+        flower lily \
+        mf ly \
+        tex ps scm \
+        po make \
+        elisp vim \
+        input \
+        stepmake $(documentation-dir)
+@end example
+
+So that's how we get the main make loop...
+
+That loop expands like this:
+
+@example
+make PACKAGE=LILYPOND package=lilypond -C python WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C scripts WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C flower WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C lily WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C mf WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C ly WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C tex WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C ps WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C scm WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C po WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C make WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C elisp WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C vim WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C input WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C stepmake WWW-1 &&
+make PACKAGE=LILYPOND package=lilypond -C Documentation WWW-1 &&
+true
+@end example
+
+The directories up to and including vim produce no effect with
+make in non-debug mode, although debug does show lots of action.
+
+@file{git/build/input/GNUmakefile} is:
+
+@example
+depth=../
+include $(depth)/config$(if $(conf),-$(conf),).make
+include $(configure-srcdir)/./input/GNUmakefile
+MODULE_INCLUDES += $(src-dir)/$(outbase)
+@end example
+
+The first include is:
+
+@example
+..//config.make
+@end example
+
+(note the // which is strictly wrong)
+
+which has lots of variables to set, but no action occurs.
+
+The second is:
+
+@example
+lilypond-git/./input/GNUmakefile
+@end example
+
+which similarly doesn't create any actual action.
+
+An error message at the end of build/input/GNUmakefile stops
+make processing before it moves on to regression - so where does
+that come from?
+
+And the answer is - make processes all directories in the
+directory it's entered (with some exceptions like out and out-www)
+and so it changes to /regression.
+
+It then seems to consider whether it needs to make/remake loads of
+makefiles.  Don't understand this yet.  Possibly these are all the
+makefiles it's processing, and it always checks they're up to date
+before processing other files?
+
+Could be correct - some of this output is:
+
+@example
+Must remake target `../../make/ly-inclusions.make'.
+Failed to remake target file `../../make/ly-inclusions.make'.
+@end example
+
+Having decided that, it then leaves the directory and re-executes:
+
+@example
+make PACKAGE=LILYPOND package=lilypond -C regression WWW-1
+@end example
+
+The top of this make is:
+
+@example
+This program built for i486-pc-linux-gnu
+Reading makefiles...
+Reading makefile `GNUmakefile'...
+Reading makefile `../..//config.make' (search path) (no ~ expansion)...
+@end example
+
+which looks like it's re-reading all its known makefiles to check
+they're up to date.
+
+(From the make manual:
+
+To this end, after reading in all makefiles, make will consider each as a goal target and
+attempt to update it. If a makefile has a rule which says how to update it (found either
+in that very makefile or in another one) or if an implicit rule applies to it (see Chapter 10
+[Using Implicit Rules], page 103), it will be updated if necessary. After all makefiles have
+been checked, if any have actually been changed, make starts with a clean slate and reads
+all the makefiles over again. (It will also attempt to update each of them over again, but
+normally this will not change them again, since they are already up to date.)
+
+So my assumption seems correct)
+
+There appear to be about 74 of them.  After all the makefile
+checking, we get this:
+
+@smallexample
+Updating goal targets....
+Considering target file `WWW-1'.
+File `WWW-1' does not exist.
+Considering target file `local-WWW-1'.
+File `local-WWW-1' does not exist.
+Considering target file `out-www/collated-files.texi'.
+File `out-www/collated-files.texi' does not exist.
+Looking for an implicit rule for `out-www/collated-files.texi'.
+Trying pattern rule with stem `collated-files.texi'.
+Trying implicit prerequisite `collated-files.texi.in'.
+Trying pattern rule with stem `collated-files.texi'.
+Trying implicit prerequisite `collated-files.texi.in'.
+Trying pattern rule with stem `collated-files'.
+Trying implicit prerequisite `collated-files.tely'.
+Trying pattern rule with stem `collated-files'.
+Trying implicit prerequisite `out-www/collated-files.tely'.
+Trying rule prerequisite `out-www/version.itexi'.
+Found prerequisite `out-www/version.itexi' as VPATH `/home/phil/lilypond-git/input/regression/out-www/version.itexi'
+@end smallexample
+
+grep finds this if searching for local-WWW-1:
+
+@example
+make/lysdoc-targets.make:
+  local-WWW-1: $(outdir)/collated-files.texi $(outdir)/collated-files.pdf
+@end example
+
+which means that local-WWW-1 depends on coll*.texi and coll*.pdf
+and so these will need to be checked to see if they're up to date.
+So make needs to find rules for both of those and (as it says) it
+certainly needs to make coll*.texi, since it doesn't exist.
+
+In ly-rules.make we have:
+
+@example
+.SUFFIXES: .doc .tely .texi .ly
+@end example
+
+which I'll work out at some point, and also this rule:
+
+@smallexample
+$(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
+  LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
+@end smallexample
+
+Note that the recipe is a very long line - it could probably
+benefit from splitting.  The same makefile also has:
+
+@smallexample
+$(outdir)/%.texi: $(outdir)/%.tely $(outdir)/version.itexi $(DOCUMENTATION_LOCALE_TARGET) $(INIT_LY_SOURCES) $(SCHEME_SOURCES)
+  LILYPOND_VERSION=$(TOPLEVEL_VERSION) $(PYTHON) $(LILYPOND_BOOK) $(LILYPOND_BOOK_INCLUDES) --process='$(LILYPOND_BOOK_PROCESS) $(LILYPOND_BOOK_INCLUDES) $(LILYPOND_BOOK_LILYPOND_FLAGS)' --output=$(outdir) --format=$(LILYPOND_BOOK_FORMAT) $(LILYPOND_BOOK_FLAGS) $<
+@end smallexample
+
+@noindent
+which seems to be an almost exact duplicate.  Whatever, the first
+one is executed first.  Have not checked if the second executes.
+
+The first recipe translates as this:
+
+@example
+LILYPOND_VERSION=2.15.0 /usr/bin/python   --process=' ' \
+  --output=./out-www --format= --lily-output-dir \
+    /home/phil/lilypond-git/build/out/lybook-db
+@end example
+
+@noindent
+if we stop the build with an $(error), but I think this is because
+we need to allow it to process the dependencies first.  It looks
+like foo.texi is shown as being dependent on foo.tely, plus a load
+of other files.
+
+@example
+DOCUMENTATION_LOCALE_TARGET is blank
+INIT_LY_SOURCES = /home/phil/lilypond-git/scm/auto-beam.scm \
+  /home/phil/lilypond-git/scm/autochange.scm
+@end example
+
+plus 10s (100s?) of other .scm files.
+
+@example
+SCHEME_SOURCES = /home/phil/lilypond-git/ly/Welcome-to-LilyPond-MacOS.ly \
+  /home/phil/lilypond-git/ly/Welcome_to_LilyPond.ly
+@end example
+
+ditto .ly files.  This does seem a teency bit wrong - it looks like
+the .ly and .scm files have been interchanged.  ly-vars.make has
+these 2 lines:
+
+@example
+INIT_LY_SOURCES = $(wildcard $(top-src-dir)/scm/*.scm)
+SCHEME_SOURCES = $(wildcard $(top-src-dir)/ly/*.ly)
+@end example
+
+Looks like a bug.....
+
+So it now works its way through all these files, checking if they
+need to be remade.  This is 100s of lines of the debug listing,
+although none in the normal list.  Clearly none has to be made
+since they're source files.  It concludes:
+
+@example
+Must remake target `out-www/collated-files.tely'
+@end example
+
+@file{lysdoc-rules.make} has this:
+
+@smallexample
+$(outdir)/collated-files.tely: $(COLLATED_FILES)
+       $(LYS_TO_TELY) --name=$(outdir)/collated-files.tely --title="$(TITLE)" --author="$(AUTHOR)" $^
+@end smallexample
+
+@file{lysdoc-vars.make} has:
+
+@example
+COLLATED_FILES = $(sort $(TEXINFO_SOURCES) $(LY_FILES) $(OUT_LY_FILES) )
+@end example
+
+We find that:
+
+@example
+TEXINFO_SOURCES = AAA-intro-regression.tely
+OUT_LY_FILES is empty
+@end example
+
+so LY_FILES has the big long list of all the .ly files in the
+regression directory.
+
+This kicks off
+
+@example
+/home/phil/lilypond-git/build/scripts/build/out/lys-to-tely
+@end example
+
+with a list of all the files in the regression test directory. This
+should (I believe) create the file collated-files.tely.
+
+So the next rule in make is for @file{version.itexi}, and make duly
+checks this.  There's a rule in @file{doc-i18n-root-rules.make} that this
+depends on @file{git/VERSION}:
+
+@smallexample
+$(outdir)/version.%: $(top-src-dir)/VERSION
+       $(PYTHON) $(top-src-dir)/scripts/build/create-version-itexi.py > $@
+@end smallexample
+
+This causes create-version-itexi.py to run and create
+version.itexi.
+
+Once that's done, all the other *.scm and *.ly files are checked
+and since they have no rules associated, they aren't remade (just
+as well for source files, really).  Since version.itexi was remade
+make concludes that collated-files.texi must be remade.  To do
+this, it runs lilypond-book.py on collated-files.tely, as below:
+
+@example
+LILYPOND_VERSION=2.15.0
+  /usr/bin/python
+  /home/phil/lilypond-git/scripts/lilypond-book.py
+    -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
+    --process='/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'
+    --output=./out-www
+    --format=texi-html
+    --verbose
+    --lily-output-dir /home/phil/lilypond-git/build/out/lybook-db
+    out-www/collated-files.tely
+@end example
+
+So - lilypond-book runs on:
+
+@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
 
@@ -479,15 +963,42 @@ The file @file{lily-bib.bst} also has fairly extensive commenting.
 Start here: @file{make/website.make}
 
 The overall build system begins with @ref{How stepmake works}.
+Summary: when you type @code{make website} this ends up running
+@file{GNUmakefile.in} in the @file{git} directory.  Right at the
+bottom, this has the lines:
+
+@example
+# we want this separate for security; see CG 4.2.  -gp
+website:
+       $(MAKE) config_make=$(config_make) \
+               top-src-dir=$(top-src-dir) \
+               -f $(top-src-dir)/make/website.make \
+               website
+@end example
+
+On my system this expands to:
+
+@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
 
-However, we do believe that note that *none* of the variables that
+We see that the @code{$(MAKE)} expands to
+@code{make --no-builtin-rules} which is how @code{MAKE} is
+defined higher up the makefile.  The -f switch defines the
+makefile to be used - in this case
+@file{git/make/website.make}.  That's where all the action
+happens.
+
+We believe that note that *none* of the variables that
 are loaded (from depth to version numbers to whatever) are used in
 @file{website.make}.  Instead, @file{website.make} sets up its own
 variables at the top of the file.  If you're wondering if there's
 some smart reason for this, then the answer is "no".  It's because
-I didn't know/trust the original variables when I was writing that
-file.
-
+I (GP) didn't know/trust the original variables when I was writing
+that file.
 
 Website build includes @ref{Building a bibliography}.
 
@@ -500,6 +1011,7 @@ build system.  Please run:
 make -n website &> my-file.txt
 @end example
 
+to see the full output from the make.
 
 @subsubheading website.make variables
 
@@ -522,9 +1034,15 @@ Parts of @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 python scripts to define teinxfo macros.
+this calls the python scripts below:
 
 @itemize
 @item
@@ -568,7 +1086,9 @@ of @@node's [sic teenager pluralization rule] from the file.
 
 @item
 @code{website-bib:}
-generates the bibliography texinfo files from the .bib files.
+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:}
@@ -576,6 +1096,20 @@ 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.
@@ -617,13 +1151,30 @@ bottom of html pages, and adds the google analytics javascript.
 It also has hard-coded lilypond version numbers, which is Bad
 (tm).
 
-@item
-@code{website:}
-this is the "master" rule.  It calls the bits and pieces in order,
-then copies some extra files around.
-
 @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