Frequently asked question about ucampas
Can I call ucampas from Windows?
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 by extending its right-click context menu for HTML files:
First, if you haven't already done so, install PuTTY using the Windows installer. Then set up a PuTTY profile to login to sandy.cl.cam.ac.uk (preferably via Kerberos), and save this profile as “sandy.cl.cam.ac.uk”.
Then open the folder \\elmer.cl.cam.ac.uk\www\tools\windows and double-click there on the file ucampas.reg.
When you now right-click in Explorer on any HTML file, you will see several new actions:
- 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.
- ucampas -r
- recurses over all sub-pages as well.
- deletes all ucampas-generated output files in a folder (and its subfolders), i.e. each *.html file for which there exists a *-b.html source in the same folder.
These actions only work for files located on the Computer Laboratory filer, not for any files on a local disk of our PC. They depend on the tool /anfs/www/tools/bin/filerpath to translate Windows/SMB UNC filer paths into corresponding Unix/NFS paths.
Note: The ucampas.reg file (UTF-16LE plaintext) can also be loaded with the CMD command line reg import ucampas.reg. It adds to the registry the key “HKEY_CURRENT_USER\Software\Classes\SystemFileAssociations\.html\shell” and several sub keys, which define new verbs in the Explorer context menu for file type “.html”, which all call BAT files located in \\elmer.cl.cam.ac.uk\www\tools\windows. It also adds to the registry entry “HKEY_CURRENT_USER\Software\Microsoft\Command Processor” the value “DisableUNCCheck=1” such that the CMD command-line interpreter no longer complains about the current working directory being a UNC path.
If you use TortoiseSVN on a network drive: The overlay icons will not show up by default. You can fix that in TortoiseSVN | Settings | Look and Feel | Icon Overlays. Note that enabling overlays for network drives will slow down not only TortoiseSVN but the whole system and the TortoiseSVN FAQ advises against storing a working copy on a network share.
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:
- the *-b.html source file of the web page,
- any uconfig.txt file in the same or any higher-up directory,
- 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:
(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.