Computer Laboratory

Frequently asked question about ucampas

Can I call ucampas from Windows XP?

Ucampas does not yet run under Windows, but you can use PuTTY to call ucampas on a Linux server. You can configure Windows Explorer to make this very convenient:

First, if you haven't done so yet, install PuTTY using the Windows installer (we need plink and pageant). Then set up public-key based login to slogin-serv1.

Then, in the Windows XP (or Server 2003) Explorer, pick the menu Tools | Folder Options ... | File Types. Select there registered file type HTML and click on the “Advanced” button. Add an action with the “New ...” button. Fill in the following settings:

Action:
ucampas
Application used to perform action:
"C:\Program Files\PuTTY\plink.exe" -t -l %USERNAME% slogin-serv1.cl.cam.ac.uk "/anfs/www/tools/bin/ucampas -r \"`/anfs/www/tools/bin/filerpath '%1'`\" && sleep 3 || read -p 'Press return to continue ...'"
Use DDE:
(not ticked)

If your local username differs from your departmental username, then replace %USERNAME% with the latter.

When you now right-click in Explorer on any HTML file located on the Computer Laboratory filer, you will see an action “ucampas” that runs ucampas over that file. You can do this on either the *-b.html or the resulting *.html file, ucampas will figure out what file to process in either case. If you click on a folder, all the files in the uconfig.txt-defined navigation tree within that folder will be processed.

Note: Microsoft removed in Windows Vista and Server 2008 the advanced file-types configuration menu used above and appears to offer nothing equivalent. (The assoc and ftype commands do not appear to support the association of more than one command line with a file type. Graham Titmus suggested the ExtMan utility by S.D. Gerling.)

Can I use ucampas with "make"?

The dependency relationship between ucampas input files is far more complex than what a simple Makefile can express. Therefore, "make" is not able to identify the minimal set of pages that needs to be recompiled after a source file was edited. A web page may have to be recompiled by ucampas if any of the following files have changed:

  1. the *-b.html source file of the web page,
  2. any uconfig.txt file in the same or any higher-up directory,
  3. any other *-b.html source file whose title is listed in the breadcrumbs, navigation bar, sitemap, or similar automatically generated navigation content on the page, if its title has changed.

What we, therefore, do currently on the main website is to call ucampas immediately on any *-b.html file after that has changed, to make changes to the body of that web page immediately visible. We then start a "ucampas -r" background process that rebuilds the entire site from its root directory. This may not be quite as elegant as what "make" users are accustomed to. However, automatically extracting titles from source files substantially reduces duplication of information and the risk of inconsistency compared to many alternatives.

Some people found the following Makefile useful if they do not have ucampas in their path, however it does not automatically ensure that all web pages are updated only when necessary:

%.html: %-b.html
	/anfs/www/tools/bin/ucampas $*

all:
	/anfs/www/tools/bin/ucampas -r

clean:
	/anfs/www/tools/bin/ucampas-clean

Call "make file.html" after you have edited file-b.html, and call "make" whenever you have edited a uconfig.txt file or a page title. (Do not routinely call "make clean", because ucampas decides whether to use relative or absolute URLs in navigation links depending on whether the target exists in your working directory.)

A more elegant solution is on the long-term wishlist.

Note: There are in fact another ways of using ucampas that simplify the dependency relationship. If you specified all page titles in uconfig.txt files, using the title or navtitle attribute, then the third point above no longer applies. Each output file would depend only on its own *-b.html input file and any uconfig.txt file along the path to the root. The title attribute allows you to leave the title element in each *-b.html file empty. The dependency relationship can further be simplified by defining the entire navigation tree in a single root uconfig.txt file. Any other uconfig.txt file can then remain empty. (Other uconfig.txt files might still be needed to maintain the path to the root, unless you flatten the file tree compared to the navigation tree using nosub.)

Can I use ucampas with HTTPS?

Ucampas tries to convert the URL of any hyperlink that it inserts into a page into a relative URL. Relative URLs help to make a web site easily accessible via different protocols, such as “http://”, “https://”, and “file://”.

Make sure you have told Ucampas via the url parameter the http:// URL of your web page, otherwise Ucampas will be unable to convert a number of house-style related URLs into relative ones.

Example: Let's assume you use Ucampas to format a personal home page such as

  http://www.cl.cam.ac.uk/~mgk25/ = ~/public_html/index.html

Then make sure that Ucampas knows where that page lives in the http namespace by adding to your ~/public_html/uconfig.txt a line like:

  url="http://www.cl.cam.ac.uk/~mgk25/",

(You don't have to repeat this in subdirectories, Ucampas is smart enough to inherit the “url” attribute correctly extended across sub pages.)

Also, make sure you have not set the file_access parameter or used option -i, which prevent a number of house-style related URLs to be converted into relative ones, and therefore can break a page when accessed via HTTPS.