site.mk

Here are some generic or common Make recipes for preparing my Web sites. These notes are mainly written for myself, as I would not think that this machinery is easily exportable. The site.mk files are included from other Makefiles, and recursion is used to wander through my Web sites and subsites, each having it own site.mk. The whole thing is launched through the execution of a script named make-web, I almost never call make directly.

Predefined goals in the main Makefile are:

• all for preparing the site files which need to be
• clean for removing all prepared files
• force for preparing files regardless if they are up-to-date or not
• list for obtaining a list of all files in the site and sub-sites, one per line: pipe the result through grep -v ' ' for removing the Make clutter.

A webdir is a directory referred to by a virtual host in the Yaws configuration. It usually is of the form …/web/, has src/ and html-$(host)/ subdirectories, and holds a site.mk file and a gabarit.xsl file. File ~/entretien/mes-sites/site-Makefile is initially invoked through the make-web script. Each webdir has its own site.mk file, which contains the specific definitions and action rules. A sub-site is either a subdirectory or a symbolic link to a subdirectory (within the webdir, not within src/), which itself contains a site.mk file (it should also have a gabarit.xsl file, but this is not checked while discovering sub-sites), and the sub-site is not directly referred to in the Yaws configuration. Sub-sites are automatically handled.

Here are a few useful hints when writing the various site.mk files.

• The Make variable host is predefined to the current host. The machinery has the purpose of building an html-$(host)/ hierarchy out of various files, and this hierarchy should be fully rebuilt if ever thrown away. Never keep your sole copy of a real source file within html-$(host)/.

• Each site.mk defines the variable package_name as a single word describing the site, it is used at least in this Makefile for generating progress messages. The main other variable is rootdir for the absolute path of the webdir directory, without a trailing slash.

• Next to each site.mk file, there is a user-supplied gabarit.xsl file which is applied as an XSLT template to all HTML files for the site. These usually import ~/entretien/mes-sites/commun.xsl and because they do so, are themselves rather short. See existing gabarit.xsl files for examples.

• For each Web site, there are six tilable color ramps. Ramps are created by the ~/entretien/mes-sites/faire-dégradés.py script, out of two limiting colors given in site.mk as the value of Make variables named margin_color and caption_color; each has a value of the form '\#RRGGBB', with RR, GG and BB being two hexadecimal digits each. background.png, caption.png and margin.png are fixed ramps, while background.gif, caption.gif and margin.gif are animated, slowly moving ramps. background.* is nearly white and designed for text background. margin.* has more aggressive colors, and is meant for backgrounding menus or filling margin areas. caption.* has the same colors as margin.*, but the ramps are horizontally reversed; this is useful for menu entries.

• Setting SITE_ROOT prepares and saves the six color ramps. It also forces saving of favicon.ico and gabarit.css. Declare FAVICON to override ~/entretien/mes-sites/favicon.ico as favorite icon, STYLE and STYLEURL to override ~/entretien/mes-sites/gabarit.css and the associated URL /gabarit.css as a style sheet, and TEMPLATE to override ~/fp/web/gabarit.xsl as an XSLT template file. If the site uses a logo and rely one common templates, one may define LOGOURL as the URL for this logo.

• LOGOURL, STYLEURL and TEMPLATE may be overridden for sub-sites.

• Sources are usually kept within the src/ hierarchy of the Web site. When src/ exists, any contained file named NEWS, README, THANKS or TODO, any contained directory named archives, and files having one of the extensions .cgi, .css, .html, .gif, .jpg, .js, .mp3, .png, .rst or .txt are all automatically handled by the machinery. Some files receive special treatment : .html files are expanded through the site-specific XSLT template; .rst and .txt files are turned into HTML (respectively by Docutils or by a mere Python script), then processed via XSLT. Other files are symbolically linked.

• If there is a notes/ directory in the Web site, it is likely produced and maintained separately by my tboy tool. Its contents are handled automatically here : .html files are XLST-transformed, and .math files (holding LaTeX formulas) are converted into .png images.

• Use GOALS += List to add other files to the goal list. The listed files do not start with the string html-$(host)/, as this prefix is internally added later. Yet, when one provides rules to build these files, the target should explicitly start with html-$(host)/.