CG: more website build details.

diff --git a/Documentation/contributor/build-notes.itexi b/Documentation/contributor/build-notes.itexi
index e82bcaf5f44f7e1dbf7886a4e76eb57774c88d2a..e9d2b9190332b4db2a8a71d0fdf3198bf151f0f5 100644 (file)
--- a/Documentation/contributor/build-notes.itexi
+++ b/Documentation/contributor/build-notes.itexi
@@ -467,27 +467,51 @@ there's another bunch of lines setting up generic variables.
 
 @subsubheading website.make building parts
 
-The website-version rule creates files that define macros for
-commands like @code{@@stableDocsNotationPdf@{@}}, by calling
-python scripts.  Those scripts are:
+Parts of @file{website.make}:
 
+@itemize
+
+@item
+@code{website-version}:
+this calls python scripts to define teinxfo macros.
+
+@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
 
-The remaining parts are:
+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
+
 
-@itemize
 @item
 @code{website-xrefs:}
-creates files used for complicated "out-of-build" references.  If
-you just write @@ref@{@}, then all's groovy.  But if you do
-@@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.
+creates files used for complicated "out-of-build" references to
+@code{out-website/*.xref-map}
 
-We should have a separate @@node to discuss xrefs.  Also, take a
+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.
 
@@ -497,10 +521,14 @@ generates the bibliography texinfo files from the .bib files.
 
 @item
 @code{website-texinfo:}
-this is the money shot; it calles texi2html to generate the actual
+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.
 
+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