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.
If you view any TEI XML page on the preview site for
www.oucs.ox.ac.uk using a URL like:
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
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
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.
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.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
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.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
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:
This is saying that on the preview site the file was last
altered in revision
81039 by the username
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
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:
in the HTML head element.
The publish buttons should then appear.
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.