Copyright held by
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Further details of licences are available from our
Licences page. For more
information, contact the project director,
Born digital. Previous location: xml_encoding
Most MoEML documents, or significant fragments with mol:
prefix and accessed through the web application
with their id + .xml
.
The molagas prefix points to the shape representation of a location on MoEML’s OpenLayers3-based rendering of the Agas Map.
Links to page-images in the Chadwyck-Healey
Links to page-images in the
The mdt (MoEML Document Type) prefix used on
The mdtlist (MoEML Document Type listing) prefix used in linking attributes points to a listings page constructed from a category in the central MDT taxonomy in the includes file. There are two variants, one with the plain _subcategories
, meaning all subcategories of the category.
The molgls (MoEML gloss) prefix used on
This molvariant prefix is used on
This molajax prefix is used on
The molstow prefix is used on
Our editorial and encoding practices are documented in detail in the Praxis section of our website.
s/heand
his/herto
theyand
theirrespectively.
This manual explains how to share files using a subversion (SVN) repository. For
a summary of commonly used commands, see Commands
.
All of MoEML’s project files, including programming logic (XQuery, XSLT, etc.), are stored in an SVN repository. This repository maintains a copy of every file so that, if needed, a previous version of the website can be accessed. It also helps prevent versioning conflicts when multiple editors work on the same file.
To access data from the repository, use an SVN command-line client. This method
may seem old-fashioned, but it is an easy process that remains consistent across
different platforms (Windows, Mac, etc.). It also allows experienced users to
run functions like svn log
to see a list of all the changes made to
the repository.
This manual provides instructions for Linux, Windows and Mac users. See also tips and tricks for using SVN.
At HCMC, SVN is already installed on Linux. Editors working from their own computers will need to install SVN from the repositories of their own distribution.
First, create a directory for MoEML’s files and check out those files from SVN:
mkdir london
and pressing
the return key.home
directory to the london
directory by typing cd
london
and pressing the return key.svn checkout
https://hcmc.uvic.ca/svn/london/db/data .
and pressing the
return key. Make sure to include the s
in
https
and the space + period at the end (after
data
).The command line entries should look like this:
All the MoEML file names will scroll past as they are downloaded:
At the end of this list, the command line will show which revision was
checked out:
The revision number indicates the state of the repository. In the
above example, seventy-five changes have been committed to the repository
since it was set up. Every time a new change is committed to the repository
(see below), the revision
number will increase by one.
There is now a complete copy of MoEML’s files on your hard drive. Files can be edited in this location using Oxygen. Please remember to validate the files as you update them: invalid XML files cause problems for the website.
Since multiple editors will be adding, updating, and sometimes deleting
MoEML’s files from different locations, editors should make regular SVN
updates. Update your local files by typing svn update
into the
command line and pressing the return key. MoEML recommends that an update be
performed at the start of every session. See the example below:
In this example, a change has been made: a new file has been added
(this is indicated by the A
next to it; updated files are
indicated with a U
and deleted files with a
D
). Note that the revision number is incremented every time a
commit is made; this repository is at revision number 1043, so 1043 commits
have been made.
Permissions are required to commit files to SVN. To obtain permission, contact the MoEML team.
When changes are made to local files, they will need to be committed
(uploaded) to the repository with the commit
command:
london
directory (see above), type
svn commit
and press the return key.Updated broken ref links in
data/info/website_structure.xml
. Then press Ctrl + O to
create a file name for the revision in the repository, followed by
the return key. Then press Ctrl + X to exit the text editor.
The system has committed the changes and the revision number is now
76.
To add a new file to the repository, make sure the file is valid and follows MoEML’s encoding practices. Also double-check that the file is saved in the correct folder.
In the london
directory, type svn add
, then a
space, and then the file name. For instance, a file called
test.xml
located in the info
folder should
appear as follows:
The command line responds by echoing the folder and file name with an
A
in front of it.
Now commit the change to the server (see above); nothing is sent to the repository without an
svn commit
:
The command line will confirm that the revision has been committed.
Use caution when deleting files from SVN: deleted files can be recovered, but
recovering files is a time-consuming process. To delete a file, type
svn delete
, then a space, then the file name (in this
example, info/test.xml
):
Note that this process also deletes the local copy of the file.
Obtain a command-line client from CollabNet. Registration is required to download the program, but there is no cost. Make sure to download the correct version; there are versions for 32-bit and 64-bit Windows. Once the program is downloaded, install it by double-clicking the downloaded installer and following its instructions.
Next, open a command window (terminal) by clicking the start menu and typing
cmd
into the search box and pressing return. This action
should bring up a terminal window:
The terminal window opens in the home folder (C:\Users\[username] on Windows
7). Save MoEML’s files here in a new folder called london
:
The above commands can be copied and pasted into the command line to
avoid typos. The command line entries should look like this:mkdir london
into the
command line and then pressing the return key.home
directory to the
london
directory by typing cd london
followed by the return key.svn checkout
https://hcmc.uvic.ca/svn/london/db/data .
followed by the
return key. Make sure to include the s
in
https
and the space + period at the end (after
data
).
All the MoEML file names will scroll past as they download:
At the end of this list, the command line will show which revision was
checked out:
The revision number indicates the state of the repository. In the
above example, seventeen changes have been committed to the repository since
it was set up. Every time a new change is committed to the repository (see below), the revision
number will increase by one.
There is now a complete copy of MoEML’s files on your hard drive. Verify this
by opening Windows Explorer and navigating to the location they were checked
out (C:Users/[username]/london
):
Files can be edited in this location using Oxygen. Please remember to
validate the files as you update them: invalid XML files cause problems for
the website.
Since multiple editors will be adding, updating, and sometimes deleting
MoEML’s files from different locations, editors should make regular SVN
updates. Update your local files by typing svn update
into the
command line and pressing the return key. MoEML recommends that an update be
performed at the start of every session. See the example below:
In this example, a change has been made: a new file has been added (it
has A
next to it; updated files are indicated with a
U
and deleted files with a D
). Note that
the revision number has changed to 18.
Permissions are required to commit files to SVN. To obtain permission, contact the MoEML team.
When changes are made to a file, they will need to be committed (uploaded) to
the repository with the commit
command:
svn commit
followed by a space and -m
for message.
For example, if updates were made to the file
data/info/website_structure.xml
, commit them by typing the
following:
svn commit -m "Added copyright info to the header of
website_structure.xml."
If SVN asks you for a password, give your netlink password (the first
time your password is given, it may fail since SVN defaults to the user name
on your local computer first; in that case, SVN will also ask for a user
name—use your netlink user name). Once SVN confirms that you have rights to
commit to the respository, it will upload the changes:
The system has committed the changes and the revision number is now
19.
To add a new file to the repository, make sure the file is valid and follows MoEML’s encoding practices. Also double-check that the file is saved in the correct folder.
In the london
directory (see above), type svn
add
, then a space, and then the file name. For instance, a file
called test.xml
located in the info
folder should
appear as follows:
The command line responds by echoing the folder and filename with an
A
in front of it.
Now commit the change to the server (see above); nothing is sent to the server without an svn
commit
:
The command line will confirm that the revision has been
committed.
Use caution when deleting files from SVN: deleted files can be recovered but
recovering files is a time-consuming process. To delete a file, type
svn delete
, then a space, then the file name (in this
example, info/test.xml).
Then commit the change (see
above). Note that this process also deletes the local copy of the file.
Mountain Lion and Mavericks users can access MoEML’s subversion repository in a similar way to the Linux users because both of these operating systems are Unix-based. There are, however, a few differences of which Mac users should take note.
Though earlier Mac operating systems include subversion command tools by
default, Mountain Lion and Mavericks do not. To test whether your operating
system has these commands installed, follow these instructions:
To install the subversion command tools using Homebrew, you will need to do the
following:
terminal
by
clicking the magnifying glass in the menu bar or by typing
Command + Space. Once terminal is selected, press return
key.Terminal
from the Utilities folder
in Applications.svn checkout
and press the return key. If
terminal responds that there are Not enough arguments
provided
, the subversion commands are already installed
and you may proceed to the next section. If terminal responds that the command is
not recognized, you will need to install them.
Another approach might be using Xcode: brew help
. If it is installed, you will get
help instructions in terminal. If not, you will get a message
telling you that the command is not found. In that case, install
Homebrew by typing the following command: ruby -e "$(curl
-fsSL
https://raw.githubusercontent.com/Homebrew/install/master/install)"
and following the instructions. Note that a prerequisite to
installing Homebrew is Xcode; if it is not installed on your machine, download
it from the App store. For more on installing Homebrew, see these instructions.brew install svn
, then press return. The process
will take a few moments.
sudo rm -rf
/Library/Developer/CommandLineTools
then press
return.sudo xcode-select --install
and press
return.
Once you have made sure that your operating system has the necessary command line tools, you can check out MoEML’s files from the subversion repository.
First, create a directory for the files and check them out:
Once you’ve completed these steps, the MoEML file names will scroll
past as they are downloaded. At the end of the list, terminal will report
which revision was checked out. The files are now saved to your hard drive
and can be edited using Oxygen.mkdir
london
and pressing return.london
directory by typing cd
london
and pressing return.svn checkout
https://hcmc.uvic.ca/svn/london/db/data .
and pressing
return. Make sure to include the s
in
https
and the space + period at the end (after
data
). You may wish to copy-paste the command from
these instructions to avoid typos.
Updating local files will be exactly the same for Mountain Lion, Mavericks and Linux users alike. Please see the Linux instructions above.
Committing changes to files will svn commit
.
Instead, you will need to include the log message on one line as follows:
svn commit -m "[short description of your changes]"
(See
Linux instructions
above).
Adding and deleting files will be the same for Mountain Lion and Mavericks users as it is for Linux users (See Linux instructions on adding files and instructions on deleting files), with the exception that after committing the files, the log message needs to be entered on the same line (see above).
This section includes a few terminal commands that may speed up your work with the subversion repository.
When creating a new file for the project, even if it is just a word-processor
file with notes in it, remember to give it a descriptive file name, and do
not use punctuation or spaces in the file name. SVN can handle such
characters in file and folder names, but files with these types of names can
cause problems. For example, instead of Fred’s notes on
Stow.odt
, use Fred_notes_on_Stow.odt
.
When creating a new file, first save it in the correct SVN folder and then
enter svn add [the filename]
to tell SVN that it should be
managing the file. For instance, when creating a file in the documentation
folder, first enter svn add
documentation/Fred_notes_on_Stow.odt
. The command line should
respond with A (bin) documentation/Fred_notes_on_Stow.odt
,
meaning that SVN has accepted the file. Finally, the file needs to be
committed with the command svn commit -m "[Short description of your
changes]"
. Ex. svn commit -m "Added a file to documentation
with my notes on Stow"
.
It may sometimes be necessary to add multiple formats of the same file; this
is particularly applicable for image files. Suppose that the following image
files exist: facsimile_agas.png
,
facsimile_agas.svg
, and facsimile_agas.gif
.
Upload all three files at the same time by entering svn add
db/site/images/facsimile_agas.*
into the commmand line. The
asterix symbol in this command means .png
file, the .svg
file, and the
.gif
file together. Thus, this command will trigger the
following response:
svn add db/site/images/facsimile_agas.*
A (bin) db/site/images/facsimile_agas.png
A db/site/images/facsimile_agas.svgz
A db/site/images/facsimile_agas.gif
Finally, these file need to be committed with the command svn commit -m
"Added new image of the Agas map in three formats."
Before moving a file in SVN, make sure everyone who might have uncommitted
changes to file being moved has committed their changes. Once you have done
this, use the following command template in Terminal: svn mv [Insert
current file url.] [Insert desired file url.]
This template assumes that you are in the correct data directory (i.e., that
you have used Terminal to navigate to the folder that contains your MoEML
files, usually named london
). As the template indicates, the
svn mv
command consists of three parts: the preface
svn mv
, the file’s current url (i.e., where the file is
located now), and the file’s desired url (i.e., where you want the file to
be located).
Suppose that you want to move praxis.xml from
its current location in the how_to
folder to the
info
folder. The file’s current url is
how_to/praxis.xml
. In this hypothetical scenario, the
file’s desired url is info/praxis.xml
. To move the file, type
the following command into Terminal: svn mv how_to/praxis.xml
info/praxis.xml
. SVN will respond by deleting the original file
(in this example, how_to/praxis.xml
) and adding a new one (in
this example, info/praxis.xml
). A dialogue that looks something
like the following should occur in your Terminal window:
Finally, commit your change using the svn commit
command. Once
you commit your change, any team member who updates their SVN files will see
that the original file has been deleted and that a new version of the file
has been added in the specified location.
Commands must be typed precisely at the command line with the correct
capitalization. For example, MyFile.odt
is a different file
from myfile.odt
. However, the command line has a few helpful
shortcuts. To automatically complete a command, press tab after entering the
first two or three characters of a file name (enough to distinguish it from
any other file in the folder). For example, typesvn add doc
,
then press tab. The command line should then complete the folder name:
svn add documentation/
. Then add Fre
:
svn add documentation/Fre
and press tab. The command line
should complete the rest of the filename: svn add
documentation/Fred_notes_on_Stow.odt
.
When working at the command line, it may sometimes be necessary to repeat the
last command, or the last command with a small variation. It is possible to
use the arrow keys on the keyboard to recall previous commands. For example,
enter svn add documentation/Fred_notes_on_Stow.odt
svn commit -m "Added a file to documentation with my notes on
Stow."
then press the svn commit -m "Added a file to
documentation with my notes on Stow."
and Press the
svn add documentation/Fred_notes_on_Stow.odt
. Use the
It frequently happens that new files are created and subsequently forgotten
before being added to SVN. To find out what files have been modified in the
current session, enter svn status
. The command line will then
return a list of file names. For example:
svn status
M static/css/global.css
? static/images/facsimile_page.svg
? static/images/facsimile_page.png
In the above list, the question mark symbol precedes file names that are not currently being managed by SVN. These files, should they be relevant to MoEML, need to be added and commited to SVN.
Finally, in the above list, M
preceeds file names that have
been modified in the current session but not commited to SVN. These files
need to be commited to SVN.
The svn log
command makes it possible to read SVN logs from
recent commits, thereby enabling users to track each other’s work. To use
this command, first enter svn log -l 20
. (The character after
the dash is a lowercase L and the succeeding number tells SVN how many logs
to return.) In this example, SVN is being asked to return the most recent 20
entries; it is possible, however, to ask for more or less entries.To see the
very latest log entry, enter svn log -r HEAD
. To see the log
entry for a specific revision, enter the number of the revision after -r.
For example, svn log -r 1259
will return revision number
1259.
The command line will respond to these commands with a log entry or a series of log entries that look(s) like this:
r1259 | jenstad | 2013-05-06 16:31:33 -0700 (Mon, 06 May 2013) |
1
line Added a new file for Editorial practices for mayoral shows
editorial_practices_mayoral.xml in info.
Each individual log entry corresponds with a commit submitted to SVN. A log
entry provides the revision number, the person who did the commit, the exact
date and time of the commit, and the comment they provided. The information
provided by log entries can be very helpful when attempting to solve
mistakes and errors. For example, it is possible to see the exact changes
that were made between one revision and another in a particular file. Simply
enter svn diff -r
followed by the range of revisions (x:y) and
the file name. For example, svn diff -r 1276:1279 PERS1.xml
will return log entries for revisions to PERS1.xml numbered 1276 through to
1279.
The following is a table of common commands used when working with SVN. Each command should be followed by pressing the Enter/Return key (⏎).
For further information about how to use Subversion, consult Collins-Sussman, Fitzpatrick, and Pilato (2008).