------------------------------------------------------------------------- Migration information ===================== The tool described in this file is obsolete (as of 2007). It uses an older variant of the house style and is no longer supported. It has been superseded by the "ucampas" script, which is installed on lab-managed Linux machines as /anfs/www/tools/bin/ucampas If you still have a "something.tmpl" file for the old script, then simply call /anfs/www/html/UoCCL/template/install.pl -b something once, which converts your "something.tmpl" into a new source file "something-b.html". This you can then format into "something.html" with /anfs/www/tools/bin/ucampas something as before. You can then delete the old "something.tmpl" file and edit the new "something-b.html" in future. (Note that the new house style no longer adds the title in the top-right corner of the page, so you may want to add a

title

line at the start of the body of the new file.) To learn more about ucampas, and how it can conveniently generate breadcrumbs, navigation bars, and tables of contents automatically for you, have a look at its documentation at http://www.cl.cam.ac.uk/local/web/ucampas/ or ask pagemaster@cl.cam.ac.uk or Markus Kuhn. ------------------------------------------------------------------------- Purpose of this file ==================== The file explains how to use the scripts in: /anfs/www/html/UoCCL/template to generate a web page file in the Computer Laboratory's standard format. The main script & the commands it needs to use ============================================== The PERL script: /anfs/www/html/UoCCL/template/install.pl will take a template file (*.tmpl) and convert it to a web page file (*.html). The PERL script depends on your machine being able to run the perl command. The command line option "-s" will suppress generation of the section heading, which is the top line of the heading at the top right hand corner of the page (the default section heading is "Computer Laboratory", which is not necessarily appropriate for all pages). Your template file ================== A template file has the suffix ".tmpl" and contains the following: (1) on the first line is the title of the page, in plain text, with no HTML formatting; (2) the immediately subsequent lines may optionally specify: (i) a SECTION title to replace "Computer Laboratory" at the top right of the page (see below for how to format this); (ii) COMMENTS contact: a contact name or e-mail address to put in the footer (see below for how to format this); (iii) COPYRIGHT owner: the person or organisation in whom copyright resides (see below for how to format this); (iv) BREADCRUMBs (navigation links to higher level pages), see below for details; (v) the files which generate the page header (HEADERFILE) and footer (FOOTERFILE), see below for details; (3) the rest of the file is your web page with any HTML formatting you like. There are a number of special character sequences which you can include in your file, which will be replaced by various strings. See below for details. N.B. There is a preprocessing step which allows for nested include files. See below for details. How to run the script ===================== If your template file is called "wibble.tmpl" then the following command will produce "wibble.html": /anfs/www/html/UoCCL/template/install.pl wibble Note that you do NOT put the subscript on the file name. Makefiles handle this quite neatly (see below). What the script does to your template file ========================================== The PERL script does the following to get from .tmpl to .html: (0) The preprocessing step scans through the file looking for lines of the form: INCLUDE&filename This includes the file filename at that point in your .tmpl file. There may be several includes and they may be nested to any depth (until PERL runs out of memory!). (1) A header is added. This is usually the standard header, with your first line as title of the page (appears in the window title in Netscape and IE), as heading at the top of the page, and as the final breadcrumb. It is possible to specify a different header file, see (2)(v) below. (2) The immediately following lines can contain specific extra information to go in the automatically generated header and footer. They are of six types: SECTION, COMMENTS, COPYRIGHT, BREADCRUMB, HEADERFILE, FOOTERFILE. * There must be NO blank lines before the first of these special lines. * There must be NO blank lines between the special lines. * The special lines may be in any order. * BREADCRUMBS are put on the page in the order they appear. * For the other five commands it is the last one to appear which is the one which is used. * If the "-s" command line option is used then the SECTION is ignored. (i) SECTION A section heading can be put in to replace the "Computer Laboratory" heading at the very top right of the page. This is done by a line like this: SECTION§ion heading for example, Neil Dodgson may decide that all his pages should have the section heading: SECTION&Neil Dodgson A null section heading can be specified by: SECTION& which effectively suppresses the section heading. This can also be done at the command line using the "-s" option. (ii) COMMENTS This specifies what goes after "Please send any comments to" in the footer. It is free formatting, so can be an e-mail address or webpage reference or just a name depending on your level of paranoia. It is formatted as follows: COMMENTS&contact information The contact information can be anything, and replaces "pagemaster@cl.cam.ac.uk" in the line which reads: Please send any comments to pagemaster@cl.cam.ac.uk Examples are: COMMENTS&Neil Dodgson COMMENTS&Neil Dodgson COMMENTS&nad@cl.cam.ac.uk COMMENTS&nad@cl.cam.ac.uk The first and third examples are not as helpful to the reader as the second and fourth examples. If this line does not exist then the following is used: pagemaster@cl.cam.ac.uk. (iii) COPYRIGHT This specifies what goes after "(c) " in the footer. It is free formatting, so can be an e-mail address or webpage reference or just a name It is formatted as follows: COPYRIGHT&information The copyright information can be anything, and replaces "University of Cambridge Computer Laboratory" Examples are: COPYRIGHT&Neil Dodgson COPYRIGHT&Neil Dodgson (iv) BREADCRUMBs Any breadcrumbs are converted to correct breadcrumb format. A breadcrumb is indicated by a line in the file of the following format: BREADCRUMB&bread crumb name&http://www.cl.cam.ac.uk/web-address - The three components are separated by ampersands (&). - The first component must be the string "BREADCRUMB" - The "bread crumb name" is the string which appears for the user. - The web address is the correct HTTP specification of the link. * Note that NO spaces are allowed except in the interior of the bread crumb name. - The first (Computer Laboratory) and last (this file) breadcrumbs are generated automatically - the "-s" option does NOT affect the breadcrumbs in any way (v) HEADERFILE and FOOTERFILE These specify the files to use as templates for header and footer information. They are indicated in the following format: HEADERFILE&/homes/nad/my_templates/my_head.def FOOTERFILE&/homes/nad/my_templates/my_foot.def (3) The rest of your template file is copied into the HTML file with no changes. If you use the following placeholders in your file then the script will replace them with the Laboratory's standard HTML list format commands (this allows us to quickly change the look of the pages without great effort). ##LISTSTART## - start of a list ##ITEMHEAD## - heading of an item in the list (follow with the text of the heading, normally just one line) ##ITEMBODY## - body of an item in the list (follow with the text of the body) ##LISTEND## - end of list This was originally intended to match neatly with the HTML constructs
,
,
,
, with an image as the bullet on the
(item head). At the time of writing they are being mapped to the HTML constructs instead. You may also use the following placeholders: ##TITLE## - the page's title ##SECTION## - the section heading ##BREADCRUMBS## - the whole breadcrumb line ##FILENAME## - the name of the resulting HTML file ##DATE## - date (e.g. "on 30-Oct-2002 at 18:54") ##OWNERNAME## - file-owner's name as found in the passwd user database ##OWNERUSERID## - file-owner's user ID ##OWNEREMAIL## - file-owner's Lab e-mail address ##COMMENTCONTACT## - what is specified in the COMMENTS line ##COPYRIGHT## - the copyright owner, specified in the COPYRIGHT line ##YEAR## - the current year (4) A footer is added, this is normally the standard footer, with the date, time, your name, and either a standard e-mail address (pagemaster@cl.cam.ac.uk) or the e-mail address that you specified in the COMMENTS line in the .tmpl file. These are automatically extracted from the last-modified date and owner of the template file. It is possible to specify a different footer file, see (2)(v) above. Makefiles ========= The following three lines make the core of a useful Makefile. Typing: make wibble.html will make wibble.html from wibble.tmpl. .SUFFIXES: .tmpl .html .tmpl.html: /anfs/www/html/UoCCL/template/install.pl $* Remember that "$*" is the target filename with its suffix stripped off.