|
|
|
|
@ -1,190 +0,0 @@ |
|
|
|
|
<?xml version='1.0'?> |
|
|
|
|
|
|
|
|
|
<!DOCTYPE cscpage SYSTEM "../csc.dtd"> |
|
|
|
|
|
|
|
|
|
<cscpage title="CSC Website Editing Howto"> |
|
|
|
|
<header/> |
|
|
|
|
<section title="Getting started"> |
|
|
|
|
<p> |
|
|
|
|
In order to edit the website you will first have to get the CVS |
|
|
|
|
repository in which it is stored. To do so, go somewhere in your |
|
|
|
|
home directory and type: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
export CVS_RSH=ssh<br /> |
|
|
|
|
cvs -d username@caffeine.uwaterloo.ca:/u/www/cvsroot co www |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
Where <code>username</code> is your CSC user name. You will be |
|
|
|
|
prompted for your password (unless you use an SSH key). After a |
|
|
|
|
while you should have a new directory, <code>www/</code>, with |
|
|
|
|
the CSC pages in it. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
You will also need <code>libxslt</code> and <code>libxml</code> |
|
|
|
|
(including development headers) from Gnome. In debian, |
|
|
|
|
<code>apt-get install libxml2-dev libxslt1-dev</code>. |
|
|
|
|
</p> |
|
|
|
|
</section> |
|
|
|
|
<section title="Compiling the website"> |
|
|
|
|
<p> |
|
|
|
|
The CSC website is <i>compiled</i>. This means that when you |
|
|
|
|
edit a page, you don't edit the HTML source directly, but |
|
|
|
|
instead edit a page describing the page's <i>content</i> (and |
|
|
|
|
some formatting) and then run a command to generate the HTML |
|
|
|
|
page from these content description pages. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
To generate the CSC website, make sure you are in the directory |
|
|
|
|
into which you checked it out (the <code>www/</code> directory) |
|
|
|
|
and enter |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
make |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
This will compile the whole website. After any changes you make |
|
|
|
|
you will have to recompile the website in the same manner. |
|
|
|
|
</p> |
|
|
|
|
</section> |
|
|
|
|
<section title="Adding a regular page"> |
|
|
|
|
<p> |
|
|
|
|
Let's now suppose we want to add a page detailing what operating |
|
|
|
|
systems the CSC distributes through its CD-burning. First, we go |
|
|
|
|
to the appropriate directory, in this case probably |
|
|
|
|
<code>www/office</code>. Here we now open a new file called |
|
|
|
|
<code>operating-systems.xml</code> in our favourite text editor |
|
|
|
|
(emacs, of course). Take note that the filename ends in |
|
|
|
|
<code>.xml</code>. All CSC web pages should have this file |
|
|
|
|
ending. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
The next thing to do is to add a few standard XML things to the |
|
|
|
|
file. We add the two lines: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
<?xml version='1.0'?><br /> |
|
|
|
|
<!DOCTYPE cscpage SYSTEM "../csc.dtd"> |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
Note the reference to the file <code>../csc.dtd</code>. This |
|
|
|
|
file is located in the <code>www/</code> directory, which is the |
|
|
|
|
parent directory of <code>www/office/</code>, therefore we use |
|
|
|
|
<code>../</code>. These two lines should appear at the top of |
|
|
|
|
every CSC web page. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
Next we start the actual page. To begin, we open a |
|
|
|
|
<code>cscpage</code> tag with the title attribute set to the |
|
|
|
|
title of our page. We also want to add a header with the CSC |
|
|
|
|
logo, the current section directory and the title of the |
|
|
|
|
page. Don't worry though, as you'll see this is really easy. Add |
|
|
|
|
the following two lines to the end of the page: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
<cscpage title="Operating Systems the CSC |
|
|
|
|
distributes"><br /> |
|
|
|
|
<header /> |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
That's it! So we can see what our page looks like so far, we |
|
|
|
|
also add the footer (with the menu, generation date, and |
|
|
|
|
copyright information) and we close the <code>cscpage</code> |
|
|
|
|
tag. Add the following lines to the end: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
<footer /><br /> |
|
|
|
|
</cscpage> |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
Notice how in the case of <code>header</code> and |
|
|
|
|
<code>footer</code> we have a <code>/</code> before the |
|
|
|
|
<code>></code>? This is one of the major differences between |
|
|
|
|
HTML and XML: tags that don't really have an end tag, such as |
|
|
|
|
<code><br></code> have to be specified as being |
|
|
|
|
<i>empty</i> in XML by adding a <code>/</code> before the |
|
|
|
|
<code>></code>. This is particularily important to remember |
|
|
|
|
when you add XHTML (XML's version of HTML) to the page. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
Now we want to see what the resulting HTML page looks like. But |
|
|
|
|
first we have to tell <code>make</code> about our new page. To |
|
|
|
|
do so, open up the file <code>www/office/Makefile</code>, find |
|
|
|
|
the line beginning with <code>INPUTS = </code> and simply add |
|
|
|
|
<code>operating-systems.xml</code> to the end of that line. So |
|
|
|
|
the line might look like <code>INPUTS = index.html staff.xml |
|
|
|
|
books.xml operating-systems.xml</code>. Save |
|
|
|
|
<code>Makefile</code> and close it. Now, in the |
|
|
|
|
<code>www/</code> directory, type <code>make</code>. This will |
|
|
|
|
build the whole website, (hopefully!) including our little |
|
|
|
|
document. Once <code>make</code> is done, have a look at the |
|
|
|
|
resulting file, |
|
|
|
|
<code>www/office/operating-systems.html</code>. It should look |
|
|
|
|
like <a href="editing-example1/operating-systems.html">example |
|
|
|
|
1</a> (use your browsers Back button to return to this page |
|
|
|
|
after viewing the example). |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
Looking at the generated page, you may have noticed that it does |
|
|
|
|
not yet appear in the menu at the top of the page. Opening up |
|
|
|
|
the special file <code>www/office/directory.xml</code> you will |
|
|
|
|
see several entries, each corresponding to one of the menu |
|
|
|
|
items. After the last line beginning with |
|
|
|
|
<code><diritem</code>, add in the following line: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
<diritem title=""Operating Systems" |
|
|
|
|
href="operating-systems.html" /> |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
Now recompile the site with <code>make</code>. You should see |
|
|
|
|
that the page now looks something like <a |
|
|
|
|
href="editing-example2/operating-systems.html">example |
|
|
|
|
2</a>. Also note that all the other office pages will now have a |
|
|
|
|
reference to the new operating systems page. |
|
|
|
|
</p> |
|
|
|
|
<p> |
|
|
|
|
With that out of the way, it's time to add some content. You may |
|
|
|
|
be happy to hear that you can add regular (X)HTML to any CSC web |
|
|
|
|
page. So, we'll add the following content between the |
|
|
|
|
<code><header /></code> and <code><footer /></code> |
|
|
|
|
of the page: |
|
|
|
|
</p> |
|
|
|
|
<code> |
|
|
|
|
<section title="List of operating systems"><br/> |
|
|
|
|
<ul><br/> |
|
|
|
|
<li><a href="http://www.debian.org/">Debian GNU/Linux</a></li><br/> |
|
|
|
|
<li><a href="http://www.freebsd.org/">FreeBSD</a></li><br/> |
|
|
|
|
</ul><br/> |
|
|
|
|
<p>More operating systems may be available.</p><br/> |
|
|
|
|
</section><br/> |
|
|
|
|
</code> |
|
|
|
|
<p> |
|
|
|
|
As usual, compile your changes using <code>make</code> and have |
|
|
|
|
a look. The resulting file should look something like <a |
|
|
|
|
href="editing-example3/operating-systems.html">example 3</a>. A |
|
|
|
|
few things to keep in mind are: |
|
|
|
|
</p> |
|
|
|
|
<ul> |
|
|
|
|
<li> |
|
|
|
|
Always use lower-case in your XHTML tags. XML is |
|
|
|
|
case-sensitive. For example: <code><br/></code> is good |
|
|
|
|
whereas <code><BR/></code> is bad. |
|
|
|
|
</li> |
|
|
|
|
<li> |
|
|
|
|
Always close your tags. If it's a tag that never encloses |
|
|
|
|
anything use the <code><tag/></code> syntax. For |
|
|
|
|
example: <code><ul> <li>Item |
|
|
|
|
1<br/>Linebreak</li> <li>Item |
|
|
|
|
2</li></ul></code> is good, whereas |
|
|
|
|
<code><ul> <li>Item |
|
|
|
|
1<br>Linebreak <li>Item 2</ul></code> is bad. |
|
|
|
|
</li> |
|
|
|
|
<li> |
|
|
|
|
You must place HTML code inside <code><section></code> |
|
|
|
|
tags. You can have as many section as you want on the page. |
|
|
|
|
</li> |
|
|
|
|
</ul> |
|
|
|
|
</section> |
|
|
|
|
<footer /> |
|
|
|
|
</cscpage> |
