IT Services



Using the Publish buttons


Contents

Pages on the OUCS preview sites now have four buttons with green/red backgrounds. This document indicates how those buttons can be used to publish files to the publish site.



1. Basics

If you view any TEI XML page on the preview site for www.oucs.ox.ac.uk using a URL like:

http://www.oucs.ox.ac.uk:81/nexus/email/clients.xml

or:

https://www.oucs.ox.ac.uk:4443/nexus/email/clients.xml

you will now see four buttons that have green/red backgrounds. This also occurs for any TEI XML page on the preview site for www.ict.ox.ac.uk and also for any HTML page on the preview site for projects.oucs.ox.ac.uk/lowcarbonict.

Figure images/publish-buttons.png [Publish buttons]

The four buttons are labelled view-pub, p-help, p-file and p-dir.

If you click the p-file or the p-dir link, you will first be asked to Webauth your access to active.oucs.ox.ac.uk. If you have clicked on the p-dir link, you will get a page asking you to confirm which files you want to be copied/deleted. At this point, you need to ensure that any files you do not wish to be copied/deleted are unchecked.

After it has performed the changes, your browser will receive a new web page that reports on what happened when it tried to publish. That output is reasonably terse. If you want more information, click on the button that has the label show a more detailed version of this web page. Note: if you have JavaScript disabled, you will have no choice, as you will get the more detailed version.

There are links on this web page that enable you either to return to the page being previewed or to look at the page on the publish site.

Note: scary things (like add/removing files to/from the publish site) only happen when you click a button that has a red background; clicking a button that has a green background will not do any changes: it will just lead you to a new web page.



2. Gotchas



2.1. Filename paths with funny characters

The p-file and p-dir links will report an error if a filename path includes a funny character. The permitted characters are a slash, the letters, the digits, a dot, a hyphen and an underscore. (Note: the space character is not a permitted character.)



2.2. Situation where your preview copy needs to be updated

If you use the publish button on a file that is not yet in the publish site, the publishbutton facility will also alter the copy of the file on the preview site (to set a Subversion property). Unfortunately, this means that your copy of the preview site is now out-of-date, and you will have to use the update option of your Subversion client to get it in step. This is reported on the screen you get back when you use the publish button.



2.3. No subdirectories are published

The p-dir link only publishes files of the current directory: it does not publish any subdirectories of the current directory. This is deliberate in order to keep things simple. If you have subdirectories to publish, visit each of the subdirectories and publish each one in turn.



2.4. Requests to publish deeply nested new subdirectories are rejected

Suppose you are using the p-dir link to publish a directory. Suppose that directory is new and so it does not yet exist on the publish site. Before publishing the files of the new directory, the script will create the new directory on the publish site provided that its parent directory exists on the publish site. However, the script will reject requests to create more deeply nested new subdirectories.



2.5. Unwanted directories on the publish site are ignored

Although the p-dir link can be used to delete unwanted files from the publish site, it will not delete from the publish site any directories that are no longer in the preview site.



2.6. Concurrent uses may lead to undesired effects

Undesired effects may occur if two people are working on the same file. If person X has committed a change to a file on the preview site and person Y then commits some changes and person X then clicks the p-file button, X is then committing some changes to the publish site he/she did not make. Although one could add code to check that the publisher (X) has the same username as the person who last made a change to the file (Y), it will be more difficult to add this checking when a person is publishing a directory.



2.7. Directories that have no TEI XML file get a p-dir link

Suppose a directory on the preview site does not have a TEI XML file. So it does not have an index.xml file. When your browser visits that directory, you will get a nicely-formatted directory listing. That directory listing will include a p-dir link that can be used to publish files in that directory.



2.8. Publishing a file that is not a TEI XML file

There are two possibilities if you wish to publish to the publish site a file that is not a TEI XML file:



3. Improvements



3.1. Not all changes to a directory may be published

The p-dir script uses a svn diff --summarize command to detect the differences between the directory appearing on the publish site and the directory appearing on the preview site. The command produces one line for each file that has changed. The first character of each line of output indicates the nature of the change. Currently, the script reacts appropriately to changes identified by A, D or M. However, any others just produce a warning message.



3.2. Log does not commit using the publisher's username

Here's a typical entry in the log when a file is committed to the publish site:

r82998 | publish-button | 2009-01-13 10:49:28 +0000 (Tue, 13 Jan 2009) | 1 line Publisher: mikef, Revision: 81039, Author: rahtz, Date: 2008-11-17 21:31:15 +0000 (Mon, 17 Nov 2008)

This is saying that on the preview site the file was last altered in revision 81039 by the username rahtz on 17th November. It also says the person publishing this file to the publish site has the username mikef. However, the commit log does not record the username mikef: instead it commits using the fictitious username publish-button. Although it would be desirable to commit using the username mikef, this is not thought to be easy to do.



3.3. Getting the relaxfile

Currently, each use of the p-file or the p-dir buttons gets a new copy of the tei-oucs.rnc file. This is deliberate so that you are getting an up-to-date copy of the file.



3.4. Getting the file to be published

There is no check that the svn cat has succeeded. It will not succeed if the temporary directory becomes full.



4. Using the publish-button facility on projects.oucs.ox.ac.uk

The publish-button facility was designed for TEI XML files that are on www.oucs.ox.ac.uk. The buttons that appear in the page on the preview site are produced when the file is transformed by XSL from TEI to HTML. So it is the XSL that is generating the HTML for the buttons.

Obviously, the publish-button facility won't automatically be available to you if you are working elsewhere.

Following a request from Howard Noble, I found a way of providing the publish-button facility on a site that is in projects.oucs.ox.ac.uk. The files on this site are written in HTML. If you go to https://projects.oucs.ox.ac.uk:4443/lowcarbonict, you will see that all the pages of this site have the publish-button facility.

If you have a site on projects.oucs.ox.ac.uk that has both a preview and a publish tree, and you want publish buttons to appear on the pages that are on your preview site, each HTML file on your site has to have the lines:

<script src="/stylesheet/js/publishbutton.js" type="text/javascript"><!--
fudge--></script>

in the HTML head element.

The publish buttons should then appear.



5. Thanks

We are grateful for those that had made comments. In particular, we've had useful dialogues and constructive comments from Dom and some informal observations from Aaron.