Computer Laboratory main website -- notes for pagemaster
--------------------------------------------------------


This is the root directory of the web site http://www.cl.cam.ac.uk/.


House-style formatting tools
----------------------------

We use a standard tool for maintaining pages formatted according to
the Computer Laboratory house style. Calling

  /anfs/www/tools/bin/ucampas <filename>

converts an undecorated "bare-bones" file <filename>-b.html into a
decorated file <filename>.html. This tool also scans the filetree
vicinity for uconfig.txt files, which provide style options and
information about the structure of the navigation tree.

Detailed documentation is at: http://www.cl.cam.ac.uk/local/web/ucampas/

[A previously used (now deprecated) tool

  /anfs/www/VH-cl/html/UoCCL/template/install.pl <filename>

still exists and converts <filename>.tmpl into <filename>.html.
Documentation: /anfs/www/VH-cl/html/UoCCL/template/README ]


Files under version control
---------------------------

The main departmental web pages reside in a Subversion repository. The
URL associated with the directory in which this README.txt file is
located is

  svn+ssh://wwwsvn@svn-www.cl.cam.ac.uk/vh-cl/trunk/html

and the actual Subversion repository is owned by pseudo-user wwwsvn
and is located at

  /usr/groups/wwwsvn/repositories/vh-cl

Detailed instructions on how to get access to the repository are at

  http://www.cl.cam.ac.uk/local/web/subversion/

Pages kept in the repository are edited by committing changes from a
personal working directory to the Subversion repository. Each commit
triggers a post-commit script that then automatically updates and
reformats the corresponding files under /anfs/www/VH-cl/html/, which
is also a Subversion working directory. The automatic update applies
to all files located in directories owned by the pseudo-user
"wwwupdate".

(A small number of files are kept under version control but are not
yet in a directory owned by "wwwupdate" and will therefore not be
automatically updated under /anfs/www/VH-cl/html/. These can still be
edited directly under /anfs/www/VH-cl/html/. We aim to phase these out
eventually. These are mainly found in techreports/.)


Files not under version control
-------------------------------

We also have many files under /anfs/www/VH-cl/html/ that are not kept
in the /usr/groups/wwwsvn/repositories/vh-cl Subversion repository:

  - directories owned by individuals or individual research groups,
    such as subdirectories of

      * research group pages: /anfs/www/VH-cl/html/research/
      * some committee pages: /anfs/www/VH-cl/html/local/committees/
      * conference pages:     /anfs/www/VH-cl/html/events/

  - directories that contain large third-party-provided files not
    routinely edited locally, such as

      * manuals:              /anfs/www/VH-cl/html/manuals/

  - files generated by cron job scripts, such as those generated via

      /anfs/www/VH-cl/scripts/regular-updates

  - historic or temporary files, such as

      * old CL main pages:    /anfs/www/VH-cl/html/UoCCL/

These files are edited directly under /anfs/www/VH-cl/html/ by their
respective owners. Users collaborating on such files may want to put
the command "umask 002" into their ~/.bashrc file (or make otherwise
sure that the edited files remain writable to group members).

The group wwwpages is used for:

  - files that are maintained by pagemaster@cl and that are not
    automatically updated via the Subversion repository;

  - directories (potentially Subversion-controlled) into which
    pagemaster@cl members directly write other files that are not under
    Subversion control (e.g., PDF documents, files updated from cron jobs).
    [Such cron jobs should ideally be owned by the pseudo-user wwwupdate
    as well, but wwwupdate@slogin's crontab does not yet work, for
    reasons yet to be investigated.]

Maintenance tools
-----------------

The top-level Makefile collects a number of useful shell commands for

  - performing consistency checks between /anfs/www/VH-cl/html/ and the
    repository;

  - giving an overview over where files in the various categories
    described above are found;

  - cleaning up various metadata (e.g., mime types, executable bits)
    in the repository that some contributors might have set
    incorrectly.

Some of these tools rely on "svn status" ignoring ucampas-generated
*.{html,php} files. For this, the svn:ignore property must regularly
be updated using /anfs/www/tools/bin/ucampas-svnignore in a personal
working directory.

Some pagemasters can change ownership of files under
/anfs/www/VH-cl/html/ using a command of the form

  ssh -t slogin-serv ssh -i ~/.ssh/id_www_chown root@on-serv chown -h ...

or

  ssh-add ~/.ssh/id_www_chown
  ssh -Akt slogin-serv ssh root@on-serv chown -h ...